Translate

Translate Skill

Automatically translate new or untranslated strings from the English locale files to all other locale files, maintaining consistency with each language's existing translations.

The app uses two i18next namespaces, each backed by its own JSON file per locale:

• core → core.json (main app strings, default namespace)
• peri → peri.json (peripheral content: onboarding ob*, help-tour hts*, Pro teaser slides pts*, months / weekday abbreviations, proTeaser*Headline/Subtext)

Both files are flat key-value JSON with no nesting (keySeparator: false).

Arguments

• No argument or all: process all languages and both namespaces.
• A language code (e.g., de_DE, ja, bg): process only that language; both namespaces.
• A namespace name (core or peri): process all languages but only that namespace.
• lang=<code> and/or ns=<core|peri> (any order, comma-separated): scope the run.
  • e.g. lang=de_DE,ns=peri, ns=peri, lang=ja
• report: only show what's missing/untranslated, don't translate. Combinable with lang=/ns=.

File Paths

• Sources of truth: src/renderer/locales/en/core.json and src/renderer/locales/en/peri.json
• Target locales: every subdirectory of src/renderer/locales/ except en/
• Each locale should contain both core.json and peri.json (flat key-value JSON, no nesting). If peri.json is missing for a locale, generate it from scratch.

Step 1 — Detect what needs translating

For each namespace in scope (default: both core and peri):

1. Read the English source file (src/renderer/locales/en/<ns>.json).
2. List all directories under src/renderer/locales/ to discover target languages.
3. If a specific language was requested, only process that one; otherwise process all.
4. For each target locale, read src/renderer/locales/<lng>/<ns>.json and compare against English:
   • Missing keys: present in English but absent in the target file. (If the target file itself is missing, treat every English key as missing.)
   • Untranslated keys: value in the target is identical to the English value AND the key is NOT in the skip-list (see below).
   • Orphan keys: present in the target but absent from English (candidates for removal).
5. Print a summary table per namespace:

   [ns=peri]
   Language  | Missing | Untranslated | Orphan
   ----------|---------|--------------|-------
   de_DE     |    3    |      1       |   0
   ja        |    3    |      5       |   0
   ...

6. If the argument was report, stop here. Otherwise, ask the user for confirmation before proceeding (unless --yes was passed).

Skip-list for untranslated detection

These keys are expected to have the same value as English in many/all languages. Do NOT flag them as untranslated:

• Keys where the English value is a single symbol, number, or punctuation (e.g., "-", "/")
• Keys where the English value is a proper noun or brand name only (e.g., "TagSpaces", "Mapique")
• Keys where the English value is a widely-used English loanword that many languages keep as-is (e.g., "Ok", "Email", "Kanban")
• When in doubt, check if at least 5 other languages also have the same value as English — if so, it's likely intentional.

Step 2 — Gather translation context

For each (language, namespace) pair that needs translations:

1. Read the target file for that language and namespace, plus the same locale's other namespace file (e.g. when translating peri.json, also read core.json for context). This is critical because peri.json is small (~142 keys) and won't carry enough style signal on its own.
2. Select a context sample of ~50 existing translated key-value pairs drawn from both namespaces. Prioritize:
   • Strings thematically similar to the ones being translated (e.g., if translating onboarding slides, sample any existing onboarding-adjacent strings; if translating Pro teaser copy, sample existing marketing/feature descriptions).
   • A mix of short labels and longer descriptive strings to capture both terse and verbose style.
3. This sample will be used as a style and terminology reference when translating, ensuring:
   • Consistent tone and formality level (formal "Sie" vs informal "du" in German, etc.)
   • Consistent term choices (e.g., if "folder" has been translated as "Ordner" in German, keep using "Ordner")
   • Consistent punctuation patterns

Step 3 — Translate

For each (language, namespace) pair, translate all missing and untranslated keys:

1. Use the English value as the source text.
2. Reference the context sample from Step 2 for style/terminology consistency.
3. Apply the following rules strictly: