Translate App Locales
Workflow
Use this skill for end-to-end language work, not just a single JSON file.
- Locate the i18n entrypoint, supported language registry, base locale files, and partial namespace files.
- Add the language to the registry and import/load it wherever base locales are wired.
- Create the base locale JSON for the language.
- Translate every partial namespace that has English keys, including catch-all or "missing" files.
- Preserve the English key tree exactly for the target language.
- Preserve interpolation tokens, ICU/plural suffixes, HTML tags, component placeholders, URLs, command names, and code identifiers.
- Remove obsolete UI settings only when the user asked for product behavior changes, not as part of translation by default.
- Validate JSON parsing, key coverage, and the app build or relevant tests.
FreeCut Locale Map
For FreeCut-like repos, check all of these:
src/i18n/languages.ts: SUPPORTED_LANGUAGES, direction, native name, English name.src/i18n/index.ts: base locale imports and baseLocales.src/i18n/locales/<lang>.json: base app shell/settings/common language strings.src/i18n/locales/partials/*.json: every namespace partial. Do not skip missing.json; it may contain active export/media/preview/timeline UI.- Existing locale files: remove keys only when the source UI no longer uses them.
If the repo has a different structure, adapt the same rule: target language must cover every English leaf key that can be loaded by i18next or the app's locale loader.
Translation Rules
- Translate user-facing prose naturally in the target language.
- Keep product names such as
FreeCut unchanged unless the existing locale pattern translates them.
- Keep placeholders byte-for-byte:
{{count}}, {{name}}, <code>, <strong>, <link>, <accent>, and similar markers.
- Keep plural variants as separate keys:
_one, _other, etc.
- Keep technical acronyms when normal in the target language: FPS, GPU, URL, MP4, AAC.
- Prefer concise UI labels over literal long translations when button space is tight.
- For language toolbar chips, use two-letter uppercase base codes such as
EN, ZH, FR, TR unless the product has a different standard.
- Preserve valid UTF-8. Non-ASCII is expected in translated locale files.
Coverage Validation
Use the bundled script after editing locale files:
node <skill>/scripts/check-locale-coverage.mjs --locales src/i18n/locales --partials src/i18n/locales/partials --source en --target tr
The script verifies:
- JSON parses for base and partial locale files.
- The target base locale has all source base leaf keys.
- Each partial's target language has every source language leaf key.
If the project has no partial directory, omit --partials.
Verification
Run the repo's fastest meaningful checks:
- Locale coverage script for the target language.
- JSON parse validation if the project has custom locale loading.
- Focused tests for settings/language persistence when language controls changed.
- Build/typecheck when translations touch app wiring or TypeScript imports.
Report unrelated failures clearly and do not hide them as translation failures.
1---2name: translate-app-locales3description: Add or audit full application translations across base locale files and partial i18n namespaces. Use when the user asks to add a new language, fix incomplete translations, remove English fallbacks, verify locale coverage, move language UI, or make future app sections translated in React/TypeScript apps with JSON locale files, especially FreeCut-style src/i18n/locales plus src/i18n/locales/partials structures.4---56# Translate App Locales78## Workflow910Use this skill for end-to-end language work, not just a single JSON file.11121. Locate the i18n entrypoint, supported language registry, base locale files, and partial namespace files.132. Add the language to the registry and import/load it wherever base locales are wired.143. Create the base locale JSON for the language.154. Translate every partial namespace that has English keys, including catch-all or "missing" files.165. Preserve the English key tree exactly for the target language.176. Preserve interpolation tokens, ICU/plural suffixes, HTML tags, component placeholders, URLs, command names, and code identifiers.187. Remove obsolete UI settings only when the user asked for product behavior changes, not as part of translation by default.198. Validate JSON parsing, key coverage, and the app build or relevant tests.2021## FreeCut Locale Map2223For FreeCut-like repos, check all of these:2425- `src/i18n/languages.ts`: `SUPPORTED_LANGUAGES`, direction, native name, English name.26- `src/i18n/index.ts`: base locale imports and `baseLocales`.27- `src/i18n/locales/<lang>.json`: base app shell/settings/common language strings.28- `src/i18n/locales/partials/*.json`: every namespace partial. Do not skip `missing.json`; it may contain active export/media/preview/timeline UI.29- Existing locale files: remove keys only when the source UI no longer uses them.3031If the repo has a different structure, adapt the same rule: target language must cover every English leaf key that can be loaded by i18next or the app's locale loader.3233## Translation Rules3435- Translate user-facing prose naturally in the target language.36- Keep product names such as `FreeCut` unchanged unless the existing locale pattern translates them.37- Keep placeholders byte-for-byte: `{{count}}`, `{{name}}`, `<code>`, `<strong>`, `<link>`, `<accent>`, and similar markers.38- Keep plural variants as separate keys: `_one`, `_other`, etc.39- Keep technical acronyms when normal in the target language: FPS, GPU, URL, MP4, AAC.40- Prefer concise UI labels over literal long translations when button space is tight.41- For language toolbar chips, use two-letter uppercase base codes such as `EN`, `ZH`, `FR`, `TR` unless the product has a different standard.42- Preserve valid UTF-8. Non-ASCII is expected in translated locale files.4344## Coverage Validation4546Use the bundled script after editing locale files:4748```bash49node <skill>/scripts/check-locale-coverage.mjs --locales src/i18n/locales --partials src/i18n/locales/partials --source en --target tr50```5152The script verifies:5354- JSON parses for base and partial locale files.55- The target base locale has all source base leaf keys.56- Each partial's target language has every source language leaf key.5758If the project has no partial directory, omit `--partials`.5960## Verification6162Run the repo's fastest meaningful checks:6364- Locale coverage script for the target language.65- JSON parse validation if the project has custom locale loading.66- Focused tests for settings/language persistence when language controls changed.67- Build/typecheck when translations touch app wiring or TypeScript imports.6869Report unrelated failures clearly and do not hide them as translation failures.
walterlow