i18n-Debugging: Internationalisierungs- und Lokalisierungsfehler finden und beheben

□ Wird die richtige Sprache erkannt und geladen?
□ Sind die Übersetzungsdateien vorhanden und wohlgeformt?
□ Stimmen die Schlüssel zwischen Code und Datei überein?
□ Sind Platzhalter in der Übersetzung unversehrt?
□ Ist die i18n-Bibliothek korrekt initialisiert?
□ Landen die Übersetzungsdateien im Build?

// React (react-i18next)
const { t, i18n } = useTranslation();
console.log('Key exists:', i18n.exists('nav.home'));
console.log('Current language:', i18n.language);
console.log('Loaded namespaces:', i18n.options.ns);

// Vue (vue-i18n)
console.log('Key exists:', this.$te('nav.home'));
console.log('Current locale:', this.$i18n.locale);
console.log('Available locales:', this.$i18n.availableLocales);

// react-i18next
i18n.init({
  missingKeyHandler: (lngs, ns, key) => {
    console.warn(`Missing translation: ${key} for ${lngs.join(', ')}`);
  },
  saveMissing: true, // protokolliert alle fehlenden Schlüssel
});

// vue-i18n
const i18n = createI18n({
  missing: (locale, key) => {
    console.warn(`Missing: [${locale}] ${key}`);
  },
});

// Was ist tatsächlich geladen?
console.log('Resources:', i18n.store.data);
// Erwartet: { en: { translation: { ... } }, de: { translation: { ... } } }

// react-i18next: auf die Übersetzungen warten
import { useTranslation } from 'react-i18next';

function App() {
  const { t, ready } = useTranslation();

  if (!ready) return <Loading />;
  return <h1>{t('welcome')}</h1>;
}

// Falsch: sucht im Standard-Namespace
t('sidebar.title');

// Richtig: sucht im passenden Namespace
t('sidebar.title', { ns: 'dashboard' });

// Oder den Namespace für die ganze Komponente setzen
const { t } = useTranslation('dashboard');

// Falsch: Variable fehlt
t('greeting'); // "Hello, {{name}}!"

// Richtig
t('greeting', { name: 'Sarah' }); // "Hello, Sarah!"

const result = t('greeting', { name: userName });
console.log('Input:', { name: userName });
console.log('Output:', result);

# Schnelltest: alle Platzhalter in EN mit denen in DE vergleichen
grep -oP '\{\{.*?\}\}' locales/en.json | sort -u > en_vars.txt
grep -oP '\{\{.*?\}\}' locales/de.json | sort -u > de_vars.txt
diff en_vars.txt de_vars.txt

// en.json (korrekt)
{ "items": "You have {{count}} items in {{location}}" }

// de.json (vom Werkzeug beschädigt)
{ "items": "Du hast {{Anzahl}} Artikel in {{Standort}}" }
// Die Variablennamen wurden mitübersetzt. Der Code übergibt {count}, nicht {Anzahl}.

// react-i18next
console.log('Detected language:', i18n.language);
console.log('Languages in order:', i18n.languages); // Rückfallkette
console.log('Resolved language:', i18n.resolvedLanguage);

// Was der Browser meldet
console.log('Browser languages:', navigator.languages);
// Beispiel: ["de-DE", "de", "en-US", "en"]

// react-i18next
i18n.init({
  supportedLngs: ['en', 'de', 'fr', 'es'],
  nonExplicitSupportedLngs: true, // de-DE trifft auf de
  load: 'languageOnly', // lädt 'de' statt 'de-DE'
});

// vue-i18n
const i18n = createI18n({
  fallbackLocale: 'en',
  locale: navigator.language.split('-')[0], // 'de-DE' → 'de'
});

// Next.js App Router
// Der [locale]-Parameter aus der URL ist die Wahrheit.
// Für den ersten Aufbau nicht auf die Browsererkennung verlassen.
export default function Page({ params: { locale } }) {
  // locale aus der URL nutzen, nicht aus navigator
}

// Englisch (2 Formen)
{
  "item_one": "{{count}} item",
  "item_other": "{{count}} items"
}

// Russisch (3 Formen)
{
  "item_one": "{{count}} предмет",      // 1, 21, 31...
  "item_few": "{{count}} предмета",     // 2-4, 22-24...
  "item_many": "{{count}} предметов"    // 5-20, 25-30...
}

// Arabisch (6 Formen)
{
  "item_zero": "...",
  "item_one": "...",
  "item_two": "...",
  "item_few": "...",
  "item_many": "...",
  "item_other": "..."
}

// Alte Schreibweise (vor v21)
{ "item": "{{count}} item", "item_plural": "{{count}} items" }

// Neue Schreibweise (ab v21)
{ "item_one": "{{count}} item", "item_other": "{{count}} items" }

npm list i18next

file -bi locales/de.json
# Erwartet: application/json; charset=utf-8

// Falsch: nicht maskierte Anführungszeichen zerstören das JSON
{ "quote": "She said "hello"" }

// Richtig
{ "quote": "She said \"hello\"" }

// Auch richtig: einfache Anführungszeichen im Text
{ "quote": "She said 'hello'" }

// Beide Schreibweisen sind gültig
{ "greeting": "こんにちは" }
{ "greeting": "こんにちは" }

<!-- Apostrophe müssen maskiert werden -->
<string name="error">It\'s an error</string>

<!-- Oder den Wert in Anführungszeichen setzen -->
<string name="error">"It's an error"</string>

/* Anführungszeichen im Wert maskieren */
"greeting" = "Hello, \"World\"!";

<!-- dir-Attribut auf html oder einen Container setzen -->
<html dir="rtl" lang="ar">

/* Logische CSS-Eigenschaften */
.container {
  /* statt margin-left: */
  margin-inline-start: 1rem;

  /* statt padding-right: */
  padding-inline-end: 1rem;

  /* statt text-align: left: */
  text-align: start;
}

[dir="rtl"] .icon-forward {
  transform: scaleX(-1);
}

<!-- Richtig: den Browser machen lassen -->
<p dir="auto">السعر: 99.99€</p>

<!-- Falsch: RTL auf Zahlen erzwingen -->
<p dir="rtl" style="unicode-bidi: override">السعر: 99.99€</p>

/* Beachtet dir="rtl" von selbst */
.flex-container {
  display: flex;
  /* In zweisprachigen Apps flex-direction für waagerechte Layouts nicht setzen —
     das dir-Attribut dreht die Reihenfolge bereits um. */
}

// Datum
new Intl.DateTimeFormat('de-DE').format(new Date());
// "25.3.2026"

new Intl.DateTimeFormat('en-US').format(new Date());
// "3/25/2026"

new Intl.DateTimeFormat('ja-JP').format(new Date());
// "2026/3/25"

// Zahlen
new Intl.NumberFormat('de-DE').format(1234.56);
// "1.234,56"

new Intl.NumberFormat('en-US').format(1234.56);
// "1,234.56"

// Währung
new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(9.99);
// "9,99 €"

new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' }).format(1500);
// "￥1,500"

// Falsch: US-Format hart kodiert
const formatted = `$${price.toFixed(2)}`;

// Richtig: sprachabhängig
const formatted = new Intl.NumberFormat(locale, {
  style: 'currency',
  currency: userCurrency
}).format(price);

// Deutscher Nutzer gibt "1.234,56" ein (also 1234.56)
const value = parseFloat("1.234,56"); // liefert 1.234 — falsch

// Vor dem Parsen normalisieren
const normalized = input.replace(/\./g, '').replace(',', '.');
const value = parseFloat(normalized); // liefert 1234.56

// vite.config.ts
export default defineConfig({
  plugins: [
    // für dynamisches Laden der Sprachdateien
    // sicherstellen, dass die JSON-Dateien im Build landen
  ],
  build: {
    rollupOptions: {
      // alle Sprachdateien einschließen
    }
  }
});

// Für Bundler nicht analysierbar
const messages = await import(`./locales/${locale}.json`);

// Dem Bundler das Muster mitgeben:
// Webpack über einen webpackInclude-Kommentar
// Vite über Glob-Importe oder eine ausdrückliche Dateiliste

// für react-i18next — in die Browserkonsole einfügen
const i18n = document.querySelector('[data-i18n]')?.__i18n || window.i18n;
if (i18n) {
  console.table({
    'Current Language': i18n.language,
    'Fallback Language': i18n.options?.fallbackLng,
    'Loaded Languages': Object.keys(i18n.store?.data || {}),
    'Missing Keys Count': i18n.options?.saveMissing ? 'tracking enabled' : 'not tracked',
  });
}

// scripts/validate-i18n.ts
import fs from 'fs';
import path from 'path';

const LOCALES_DIR = './locales';
const BASE_LOCALE = 'en';

function validateTranslations() {
  const basePath = path.join(LOCALES_DIR, `${BASE_LOCALE}.json`);
  const baseKeys = getAllKeys(JSON.parse(fs.readFileSync(basePath, 'utf-8')));
  const errors: string[] = [];

  const localeFiles = fs.readdirSync(LOCALES_DIR).filter(f => f.endsWith('.json') && f !== `${BASE_LOCALE}.json`);

  for (const file of localeFiles) {
    const locale = file.replace('.json', '');
    const content = JSON.parse(fs.readFileSync(path.join(LOCALES_DIR, file), 'utf-8'));
    const localeKeys = getAllKeys(content);

    // fehlende Schlüssel
    for (const key of baseKeys) {
      if (!localeKeys.has(key)) {
        errors.push(`[${locale}] Missing key: ${key}`);
      }
    }

    // überzählige Schlüssel (womöglich veraltet)
    for (const key of localeKeys) {
      if (!baseKeys.has(key)) {
        errors.push(`[${locale}] Extra key (not in ${BASE_LOCALE}): ${key}`);
      }
    }

    // Platzhalter vergleichen
    for (const key of baseKeys) {
      if (localeKeys.has(key)) {
        const basePlaceholders = extractPlaceholders(getValueByPath(JSON.parse(fs.readFileSync(basePath, 'utf-8')), key));
        const localePlaceholders = extractPlaceholders(getValueByPath(content, key));

        if (basePlaceholders.sort().join(',') !== localePlaceholders.sort().join(',')) {
          errors.push(`[${locale}] Placeholder mismatch in "${key}": expected ${basePlaceholders}, got ${localePlaceholders}`);
        }
      }
    }
  }

  if (errors.length > 0) {
    console.error(`Found ${errors.length} i18n issues:\n`);
    errors.forEach(e => console.error(`  ${e}`));
    process.exit(1);
  } else {
    console.log('All translation files are consistent.');
  }
}

function getAllKeys(obj: any, prefix = ''): Set<string> {
  const keys = new Set<string>();
  for (const key in obj) {
    const fullKey = prefix ? `${prefix}.${key}` : key;
    if (typeof obj[key] === 'object' && obj[key] !== null) {
      getAllKeys(obj[key], fullKey).forEach(k => keys.add(k));
    } else {
      keys.add(fullKey);
    }
  }
  return keys;
}

function extractPlaceholders(value: string): string[] {
  if (typeof value !== 'string') return [];
  const matches = value.match(/\{\{.*?\}\}|\{[^}]+\}|%[sd@]|%\d+\$[sd@]/g);
  return matches || [];
}

function getValueByPath(obj: any, path: string): any {
  return path.split('.').reduce((o, k) => o?.[k], obj);
}

validateTranslations();

npx tsx scripts/validate-i18n.ts

# .github/workflows/ci.yml
- name: Validate translations
  run: npx tsx scripts/validate-i18n.ts

// Pseudo-Lokalisierung: Text künstlich verlängern
const pseudoLocalize = (text: string) =>
  text.replace(/[a-z]/g, c => `${c}${c}`); // verdoppelt jeden Buchstaben

// Playwright-Test
for (const locale of ['en', 'de', 'ja', 'ar']) {
  test(`homepage renders correctly in ${locale}`, async ({ page }) => {
    await page.goto(`/${locale}`);
    await expect(page).toHaveScreenshot(`home-${locale}.png`);
  });
}