|
| 1 | +# 1. SUPPORTED LANGUAGES AND LOCATION |
| 2 | + |
| 3 | +- Localize all strings into the following locale files: ca, de, en, es, fr, hi, it, ja, ko, pl, pt-BR, ru, tr, vi, zh-CN, zh-TW |
| 4 | +- The VSCode extension has two main areas that require localization: |
| 5 | + - Core Extension: src/i18n/locales/ (extension backend) |
| 6 | + - WebView UI: webview-ui/src/i18n/locales/ (user interface) |
| 7 | + |
| 8 | +# 2. VOICE, STYLE AND TONE |
| 9 | + |
| 10 | +- Always use informal speech (e.g., "du" instead of "Sie" in German) for all translations |
| 11 | +- Maintain a direct and concise style that mirrors the tone of the original text |
| 12 | +- Carefully account for colloquialisms and idiomatic expressions in both source and target languages |
| 13 | +- Aim for culturally relevant and meaningful translations rather than literal translations |
| 14 | +- Preserve the personality and voice of the original content |
| 15 | +- Use natural-sounding language that feels native to speakers of the target language |
| 16 | +- Don't translate the word "token" as it means something specific in English that all languages will understand |
| 17 | +- Don't translate domain-specific words (especially technical terms like "Prompt") that are commonly used in English in the target language |
| 18 | + |
| 19 | +# 3. CORE EXTENSION LOCALIZATION (src/) |
| 20 | + |
| 21 | +- Located in src/i18n/locales/ |
| 22 | +- NOT ALL strings in core source need internationalization - only user-facing messages |
| 23 | +- Internal error messages, debugging logs, and developer-facing messages should remain in English |
| 24 | +- The t() function is used with namespaces like 'core:errors.missingToolParameter' |
| 25 | +- Be careful when modifying interpolation variables; they must remain consistent across all translations |
| 26 | +- Some strings in formatResponse.ts are intentionally not internationalized since they're internal |
| 27 | +- When updating strings in core.json, maintain all existing interpolation variables |
| 28 | +- Check string usages in the codebase before making changes to ensure you're not breaking functionality |
| 29 | + |
| 30 | +# 4. WEBVIEW UI LOCALIZATION (webview-ui/src/) |
| 31 | + |
| 32 | +- Located in webview-ui/src/i18n/locales/ |
| 33 | +- Uses standard React i18next patterns with the useTranslation hook |
| 34 | +- All user interface strings should be internationalized |
| 35 | +- Always use the Trans component with named components for text with embedded components |
| 36 | + |
| 37 | +<Trans> example: |
| 38 | + |
| 39 | +`"changeSettings": "You can always change this at the bottom of the <settingsLink>settings</settingsLink>",` |
| 40 | + |
| 41 | +``` |
| 42 | + <Trans |
| 43 | + i18nKey="welcome:telemetry.changeSettings" |
| 44 | + components={{ |
| 45 | + settingsLink: <VSCodeLink href="#" onClick={handleOpenSettings} /> |
| 46 | + }} |
| 47 | + /> |
| 48 | +``` |
| 49 | + |
| 50 | +# 5. TECHNICAL IMPLEMENTATION |
| 51 | + |
| 52 | +- Use namespaces to organize translations logically |
| 53 | +- Handle pluralization using i18next's built-in capabilities |
| 54 | +- Implement proper interpolation for variables using {{variable}} syntax |
| 55 | +- Don't include defaultValue. The `en` translations are the fallback |
| 56 | +- Always use apply_diff instead of write_to_file when editing existing translation files (much faster and more reliable) |
| 57 | +- When using apply_diff, carefully identify the exact JSON structure to edit to avoid syntax errors |
| 58 | +- Placeholders (like {{variable}}) must remain exactly identical to the English source to maintain code integration and prevent syntax errors |
| 59 | + |
| 60 | +# 6. WORKFLOW AND APPROACH |
| 61 | + |
| 62 | +- First add or modify English strings, then ask for confirmation before translating to all other languages |
| 63 | +- Use this process for each localization task: |
| 64 | + 1. Identify where the string appears in the UI/codebase |
| 65 | + 2. Understand the context and purpose of the string |
| 66 | + 3. Update English translation first |
| 67 | + 4. Create appropriate translations for all other supported languages |
| 68 | + 5. Validate your changes with the missing translations script |
| 69 | +- Flag or comment if an English source string is incomplete ("please see this...") to avoid truncated or unclear translations |
| 70 | +- For UI elements, distinguish between: |
| 71 | + - Button labels: Use short imperative commands ("Save", "Cancel") |
| 72 | + - Tooltip text: Can be slightly more descriptive |
| 73 | +- Preserve the original perspective: If text is a user command directed at the software, ensure the translation maintains this direction, avoiding language that makes it sound like an instruction from the system to the user |
| 74 | + |
| 75 | +# 7. COMMON PITFALLS TO AVOID |
| 76 | + |
| 77 | +- Switching between formal and informal addressing styles - always stay informal ("du" not "Sie") |
| 78 | +- Translating or altering technical terms and brand names that should remain in English |
| 79 | +- Modifying or removing placeholders like {{variable}} - these must remain identical |
| 80 | +- Translating domain-specific terms that are commonly used in English in the target language |
| 81 | +- Changing the meaning or nuance of instructions or error messages |
| 82 | +- Forgetting to maintain consistent terminology throughout the translation |
| 83 | + |
| 84 | +# 8. QUALITY ASSURANCE |
| 85 | + |
| 86 | +- Maintain consistent terminology across all translations |
| 87 | +- Respect the JSON structure of translation files |
| 88 | +- Watch for placeholders and preserve them in translations |
| 89 | +- Be mindful of text length in UI elements when translating to languages that might require more characters |
| 90 | +- Use context-aware translations when the same string has different meanings |
| 91 | +- Always validate your translation work by running the missing translations script: |
| 92 | + ``` |
| 93 | + node scripts/find-missing-translations.js |
| 94 | + ``` |
| 95 | +- Address any missing translations identified by the script to ensure complete coverage across all locales |
| 96 | +
|
| 97 | +# 9. TRANSLATOR'S CHECKLIST |
| 98 | +
|
| 99 | +- ✓ Used informal tone consistently ("du" not "Sie") |
| 100 | +- ✓ Preserved all placeholders exactly as in the English source |
| 101 | +- ✓ Maintained consistent terminology with existing translations |
| 102 | +- ✓ Kept technical terms and brand names unchanged where appropriate |
| 103 | +- ✓ Preserved the original perspective (user→system vs system→user) |
| 104 | +- ✓ Adapted the text appropriately for UI context (buttons vs tooltips) |
0 commit comments