--- name: internationalization-helper description: Extracts hardcoded strings for i18n, manages translation files, and ensures locale coverage. Use when working with multi-language apps, translations, or user mentions i18n, localization, or languages. allowed-tools: Read, Grep, Glob, Write, Edit --- # Internationalization Helper Helps manage internationalization (i18n) and localization (l10n) in multi-language applications. ## When to Use - User requests i18n support - Adding new languages - Finding untranslated strings - Managing translation files - User mentions "translation", "i18n", "l10n", "locale" ## Instructions ### 1. Detect i18n Framework **JavaScript/React:** - react-i18next - react-intl (FormatJS) - i18next - LinguiJS **Vue:** - vue-i18n **Python:** - gettext - Django i18n - Flask-Babel **Ruby/Rails:** - I18n gem (built-in) Look for imports, config files, or translation directories. ### 2. Find Hardcoded Strings Search for untranslated text: ```javascript // Bad: Hardcoded

Welcome, {user.name}!

// Good: Translated

{t('welcome.message', { name: user.name })}

``` **Search patterns:** - Strings in JSX/template tags - Alert/error messages - Form labels and placeholders - Button text - Validation messages Exclude: code comments, console.log, test strings ### 3. Extract to Translation Files **React-i18next format (JSON):** ```json { "common": { "submit": "Submit", "cancel": "Cancel" }, "welcome": { "message": "Welcome, {{name}}!" } } ``` **Gettext format (.po):** ```po msgid "submit_button" msgstr "Submit" msgid "welcome_message" msgstr "Welcome, %(name)s!" ``` ### 4. Organize Translation Keys **Best practices:** - Namespace by feature: `users.profile.title` - Group common strings: `common.buttons.save` - Describe context, not content: `errors.login.invalid` not `errors.wrong_password` - Consistent naming convention ### 5. Check Translation Coverage Compare locale files to find missing translations: ``` en.json: 150 keys es.json: 142 keys (missing 8) fr.json: 150 keys ✓ Missing in es.json: - users.profile.bio - settings.privacy.title [...] ``` ### 6. Handle Pluralization Different languages have different plural rules: ```javascript // react-i18next t('items', { count: 0 }) // "0 items" t('items', { count: 1 }) // "1 item" t('items', { count: 5 }) // "5 items" // Translation file { "items_zero": "{{count}} items", "items_one": "{{count}} item", "items_other": "{{count}} items" } ``` ### 7. Date, Time, Number Formatting Use locale-aware formatting: ```javascript // Numbers const price = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(29.99); // Dates const date = new Intl.DateTimeFormat('fr-FR').format(new Date()); ``` ### 8. RTL (Right-to-Left) Support For Arabic, Hebrew: - CSS: `direction: rtl;` - HTML: `` - Logical properties: `margin-inline-start` instead of `margin-left` ### 9. Generate Translation Template Create template for new locale: ```bash # Copy keys from base language, empty values cp locales/en.json locales/de.json # Mark for translation ``` ### 10. Best Practices - Keep translations in separate files - Use keys, not source text as keys - Provide context to translators - Test with long strings (German often longer) - Use ICU MessageFormat for complex strings - Avoid concatenating translated strings - Extract all user-facing text ## Supporting Files - `templates/i18n-config.js`: Configuration examples - `templates/locale-file.json`: Translation file template