i18n Debugging Guide — Find and Fix Internationalization & Localization Issues

□ Is the correct locale being detected/loaded?
□ Are translation files present and properly formatted?
□ Are translation keys matching between code and files?
□ Are placeholders/variables intact in translations?
□ Is the i18n library properly initialized?
□ Are there build/bundling issues with translation files?

// 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, // logs all missing keys
});

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

// Check what's actually loaded
console.log('Resources:', i18n.store.data);
// Should output: { en: { translation: { ... } }, de: { translation: { ... } } }

// react-i18next: wait for translations
import { useTranslation } from 'react-i18next';

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

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

// Looks in default namespace
t('sidebar.title');

// Looks in correct namespace
t('sidebar.title', { ns: 'dashboard' });

// Or set namespace for the entire component
const { t } = useTranslation('dashboard');

// Variable missing
t('greeting'); // "Hello, {{name}}!"

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

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

# Quick check: find all placeholders in EN, verify they exist in DE
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 (correct)
{ "items": "You have {{count}} items in {{location}}" }

// de.json (corrupted by bad translation tool)
{ "items": "Du hast {{Anzahl}} Artikel in {{Standort}}" }
// Variable names were translated! Code passes {count}, not {Anzahl}

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

// Check browser header
console.log('Browser languages:', navigator.languages);
// Example: ["de-DE", "de", "en-US", "en"]

// react-i18next
i18n.init({
  supportedLngs: ['en', 'de', 'fr', 'es'],
  nonExplicitSupportedLngs: true, // de-DE will match de
  load: 'languageOnly', // loads 'de' instead of 'de-DE'
});

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

// Next.js App Router
// The [locale] param from the URL is the source of truth
// Don't rely on browser detection for initial render
export default function Page({ params: { locale } }) {
  // Use locale from URL, not from navigator
}

// English (2 forms)
{
  "item_one": "{{count}} item",
  "item_other": "{{count}} items"
}

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

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

// Old syntax (pre-v21)
{ "item": "{{count}} item", "item_plural": "{{count}} items" }

// New syntax (v21+)
{ "item_one": "{{count}} item", "item_other": "{{count}} items" }

npm list i18next

// count is just a regular variable — no plural selection
t('item', { count: 5 });

// count triggers plural form selection in i18next
// (this is actually the same syntax — make sure the key has _one/_other suffixes)

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

// Unescaped quotes break JSON
{ "quote": "She said "hello"" }

// Properly escaped
{ "quote": "She said \"hello\"" }

// Or use single quotes in the text (no escaping needed in JSON)
{ "quote": "She said 'hello'" }

// Both are valid
{ "greeting": "こんにちは" }
{ "greeting": "\u3053\u3093\u306B\u3061\u306F" }

<!-- Apostrophes must be escaped in Android XML -->
<string name="error">It\'s an error</string>

<!-- Or use quotes -->
<string name="error">"It's an error"</string>

/* Must use escaped quotes for the value */
"greeting" = "Hello, \"World\"!";

<!-- Set dir attribute on html or a container -->
<html dir="rtl" lang="ar">

/* CSS Logical Properties (modern approach) */
.container {
  /* Instead of margin-left, use: */
  margin-inline-start: 1rem;

  /* Instead of padding-right, use: */
  padding-inline-end: 1rem;

  /* Instead of text-align: left, use: */
  text-align: start;
}

/* Flip icons in RTL */
[dir="rtl"] .icon-forward {
  transform: scaleX(-1);
}

<!-- Let the browser handle bidirectional text -->
<p dir="auto">السعر: 99.99€</p>

<!-- Forcing RTL on numbers -->
<p dir="rtl" style="unicode-bidi: override">السعر: 99.99€</p>

/* This respects dir="rtl" automatically */
.flex-container {
  display: flex;
  /* Don't set flex-direction for horizontal layouts in bilingual apps */
  /* The dir attribute handles reversal */
}

// Date formatting
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"

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

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

// Currency
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"

// Hardcoded US format
const formatted = `$${price.toFixed(2)}`;

// Locale-aware
const formatted = new Intl.NumberFormat(locale, {
  style: 'currency',
  currency: userCurrency
}).format(price);

// German user enters "1.234,56" (German format for 1234.56)
const value = parseFloat("1.234,56"); // Returns 1.234 (wrong!)

// Fix: normalize input format before parsing
const normalized = input.replace(/\./g, '').replace(',', '.');
const value = parseFloat(normalized); // Returns 1234.56

// vite.config.ts
export default defineConfig({
  plugins: [
    // For dynamic locale loading
    // Ensure JSON files are in the build output
  ],
  build: {
    rollupOptions: {
      // Include all locale files
    }
  }
});

// Fully dynamic — bundlers can't analyze this
const messages = await import(`./locales/${locale}.json`);

// Give bundlers a hint about the path pattern
const messages = await import(`./locales/${locale}.json`);
// Webpack: add a webpackInclude comment
// Vite: uses glob imports or explicit file listing

// For react-i18next — paste in browser console
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);

    // Check for missing keys
    for (const key of baseKeys) {
      if (!localeKeys.has(key)) {
        errors.push(`[${locale}] Missing key: ${key}`);
      }
    }

    // Check for extra keys (possibly outdated)
    for (const key of localeKeys) {
      if (!baseKeys.has(key)) {
        errors.push(`[${locale}] Extra key (not in ${BASE_LOCALE}): ${key}`);
      }
    }

    // Check placeholder consistency
    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-localization: replace text with longer versions for testing
const pseudoLocalize = (text: string) =>
  text.replace(/[a-z]/g, c => `${c}${c}`); // doubles every letter

// 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`);
  });
}