---
name: translate
description: Translate new or untranslated i18n strings from the English locale files (core.json + peri.json) into all other locales, maintaining consistency with each language's existing translations.
---

# 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:

### Translation Rules

- **NEVER modify `en/core.json` or `en/peri.json`** — both are read-only for this skill.
- **Preserve `{{variables}}` exactly** — template placeholders like `{{fileName}}`, `{{version}}`, `{{count}}`, `{{folderName}}` must appear in the translation unchanged. Do not translate, reorder, or remove them.
- **Preserve HTML tags exactly** — tags like `<br>`, `<b>`, `</b>`, `<a>` etc. must remain intact.
- **Keep technical terms in English** across all languages: TagSpaces, Kanban, Markdown, HTML, S3, WebDAV, AI, URL, QR, EXIF, FolderViz, Mapique, JSON, PDF, EPUB, CSV, ZIP, GPX, KML, Pro.
- **German (de_DE) specific**: Use "Tags" for tags, NOT "Schlagwort/Schlagwörter". The English loanword "Tags" is the project standard.
- **Match existing tone**: If a language uses formal address (e.g., "Sie" in German, "Vous" in French), maintain that. If informal, maintain that. Determine this from the existing translations.
- **Natural phrasing**: Translations should read naturally in the target language, not be word-for-word calques from English.
- **Translate language by language** (not key by key) to maintain internal consistency within each locale. Within a language, finish one namespace before starting the next so style stays unified across both files.

## Step 4 — Write results

For each modified locale + namespace:

1. Construct the full target JSON with:
   - **The same key order as the matching English file** (`en/core.json` for core, `en/peri.json` for peri). This keeps diffs clean and structure consistent.
   - All existing translations preserved (only missing/untranslated keys get new values).
   - Orphan keys removed (keys not present in the corresponding English file).
2. Write the file using the Write tool or Edit tool as appropriate. End the file with a single trailing newline (matches existing files).
3. **Validate JSON**: After writing, verify the file is valid JSON (use `node -e "JSON.parse(require('fs').readFileSync('path'))"` or equivalent).
4. Print a final summary, one row per (language, namespace):
   ```
   Language  | NS    | Added | Updated | Removed | Status
   ----------|-------|-------|---------|---------|-------
   de_DE     | core  |   3   |    1    |    0    |  OK
   de_DE     | peri  |   2   |    0    |    0    |  OK
   ja        | core  |   3   |    5    |    0    |  OK
   ja        | peri  |   0   |    0    |    0    |  OK
   ...
   ```

## Performance Strategy

- For a single language + single namespace: process directly in the main conversation.
- For all 33 languages and/or both namespaces: use the Agent tool to parallelize. Launch multiple agents, each handling a batch of ~4-5 languages (and both namespaces together so style stays consistent within a locale). Each agent receives:
  - The full English `core.json` and `peri.json`
  - The list of missing/untranslated keys per (language, namespace) (from Step 1)
  - The target language files to process (both namespaces)
  - These translation rules

## Edge Cases

| Case | Handling |
|---|---|
| Value same as English but intentional | Use the skip-list; also check if 5+ other languages have the same value |
| New language directory with empty/missing `core.json` or `peri.json` | Generate a complete translation from scratch for the missing file(s) |
| Locale has `core.json` but no `peri.json` | Create `peri.json` from scratch, translating every English peri key |
| Locale has `peri.json` but no `core.json` | Same in reverse — unusual but handle symmetrically |
| Key has only whitespace or empty string in target | Treat as untranslated |
| English value contains line breaks (`\n`) | Preserve line breaks in translation |
| English value is very long (100+ chars) | Translate fully, do not truncate |
| Key moved between `core` and `peri` namespaces | Detect by checking if an "orphan" in core appears in `en/peri.json` (or vice versa). Report as informational only; do not auto-migrate translations — the namespace split is a separate manual operation. |