i18n Localization Skill

Description

This skill provides comprehensive internationalization (i18n) support for web applications. It manages translation files, extracts translatable strings from code, validates translations for completeness, handles locale-specific formatting (dates, numbers, currencies), and implements RTL layout support. Works with i18next, react-intl, vue-i18n, and custom solutions.

Instructions

1. Audit: Scan codebase for hardcoded strings that should be translated
2. Extract: Generate translation keys and source locale file from code
3. Validate: Compare locale files to find missing, unused, or outdated translations
4. Format: Apply locale-specific formatting rules for dates, numbers, and currencies
5. RTL: Implement right-to-left layout support for Arabic, Hebrew, etc.

Rules

• Use ICU message format for pluralization and interpolation
• Never concatenate translated strings -- use interpolation instead
• Keep translation keys semantic (user.profile.title) not positional (page3.section2.text)
• Always include a context comment for ambiguous strings
• Validate that all locales have the same set of keys
• Handle pluralization rules correctly (some languages have 6+ plural forms)
• Dates and numbers must use Intl.DateTimeFormat and Intl.NumberFormat, never manual formatting
• Support RTL: use logical CSS properties (margin-inline-start not margin-left)
• Never hardcode locale lists -- load supported locales from configuration

Translation File Structure

Recommended: Nested JSON (i18next)

Copy
{
  "common": {
    "save": "Save",
    "cancel": "Cancel",
    "delete": "Delete",
    "loading": "Loading..."
  },
  "auth": {
    "login": {
      "title": "Sign In",
      "email_label": "Email Address",
      "password_label": "Password",
      "submit": "Sign In",
      "forgot_password": "Forgot your password?"
    },
    "errors": {
      "invalid_credentials": "Invalid email or password.",
      "account_locked": "Account locked. Try again in {{minutes}} minutes."
    }
  },
  "dashboard": {
    "welcome": "Welcome back, {{name}}!",
    "items_count": "{{count}} item",
    "items_count_plural": "{{count}} items"
  }
}

ICU Pluralization

Copy
{
  "items_count": "{count, plural, =0 {No items} one {# item} other {# items}}",
  "messages": "{count, plural, =0 {No new messages} one {# new message} other {# new messages}}"
}

Validation Script

Copy
import * as fs from 'fs';
import * as path from 'path';

function validateLocales(localesDir: string, sourceLocale = 'en') {
  const sourceFile = JSON.parse(
    fs.readFileSync(path.join(localesDir, `${sourceLocale}.json`), 'utf-8')
  );
  const sourceKeys = flattenKeys(sourceFile);

  const localeFiles = fs.readdirSync(localesDir).filter(f => f.endsWith('.json'));
  const report: Record<string, { missing: string[]; extra: string[]; empty: string[] }> = {};

  for (const file of localeFiles) {
    const locale = path.basename(file, '.json');
    if (locale === sourceLocale) continue;

    const localeData = JSON.parse(fs.readFileSync(path.join(localesDir, file), 'utf-8'));
    const localeKeys = flattenKeys(localeData);

    report[locale] = {
      missing: sourceKeys.filter(k => !localeKeys.includes(k)),
      extra: localeKeys.filter(k => !sourceKeys.includes(k)),
      empty: localeKeys.filter(k => getNestedValue(localeData, k) === ''),
    };
  }
  return report;
}

Locale Coverage Report

Copy
## Translation Coverage

| Locale | Total Keys | Translated | Missing | Coverage |
|--------|-----------|-----------|---------|----------|
| en (source) | 245 | 245 | 0 | 100% |
| es | 245 | 238 | 7 | 97.1% |
| fr | 245 | 245 | 0 | 100% |
| de | 245 | 220 | 25 | 89.8% |
| ja | 245 | 198 | 47 | 80.8% |
| ar (RTL) | 245 | 189 | 56 | 77.1% |

### Missing in `de`:
- dashboard.chart.tooltip_format
- settings.notifications.frequency_label
...

Examples

"Scan src/ for hardcoded English strings that need i18n"
"Validate all locale files against the English source"
"Add German translations for the new settings page"
"Set up RTL support for Arabic locale"
"Convert our string concatenation patterns to ICU message format"