Translate

Step 1 — Detect what needs translating

1. Read _locales/en/messages.json (the English source).
2. List all directories under _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 its messages.json and compare against English:
   • Missing keys: present in English but absent in the target file.
   • Untranslated keys: message value in the target is identical to the English message 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 to the user:

   Language  | Missing | Untranslated | Orphan
   ----------|---------|--------------|-------
   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:

• appName — brand name, kept as "TagSpaces Web Clipper" in all languages
• optionsTutorialLink — "Tutorial" is used as-is in many Romance and Latin-based languages (ca, es, es_CL, id_ID, it, pt_BR, pt_PT, and others)
• Keys where the English message is a single symbol, number, or punctuation (e.g., "-", "/")
• Keys where the English message is a proper noun or brand name only (e.g., "TagSpaces")
• Keys where the English message is a widely-used English loanword that many languages keep as-is (e.g., "Ok", "Email", "Markdown", "Tutorial")
• 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 that needs translations:

1. Read the full messages.json for that language.
2. Use all existing translated entries as a style and terminology reference, ensuring:
   • Consistent tone and formality level (formal "Sie" vs informal "du" in German, etc.)
   • Consistent term choices (e.g., if "screenshot" has been translated as "Bildschirmfoto" in German, keep using "Bildschirmfoto")
   • Consistent punctuation patterns

Step 3 — Translate

For each language, translate all missing and untranslated keys:

1. Use the English message value as the source text.
2. Reference the existing translations from Step 2 for style/terminology consistency.
3. Copy the description field from the English source as-is (descriptions stay in English for developer reference).
4. Apply the following rules strictly:

Translation Rules

• NEVER modify _locales/en/messages.json — it is read-only for this skill.
• Preserve $PLACEHOLDER$ and {{variables}} exactly — template placeholders 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, Markdown, HTML, MHTML, PDF, PNG, URL, YAML.
• German (de, de_DE) specific: Use "Tags" for tags, NOT "Schlagwort/Schlagwörter". The English loanword "Tags" is the project standard. Note: the existing German translations use "Etiketten" for tags in some places — follow the existing convention in each file for consistency, but prefer "Tags" for new translations.
• 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.

Step 4 — Write results

1. For each modified locale, construct the full messages.json with:
   • The same key order as _locales/en/messages.json (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 _locales/en/messages.json).
2. Write the file using the Write tool or Edit tool as appropriate.
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:

   Language  | Added | Updated | Removed | Status
   ----------|-------|---------|---------|-------
   de        |   3   |    1    |    0    |  OK
   ja        |   3   |    5    |    0    |  OK
   ...
   

Performance Strategy

• For a single language: process directly in the main conversation.
• For all languages: use the Agent tool to parallelize. Launch multiple agents, each handling a batch of ~4-5 languages. Each agent receives:
  • The full English messages.json
  • The list of missing/untranslated keys (from Step 1)
  • The target language files to process
  • These translation rules

Edge Cases

Practical Notes (from past runs)

• Key reordering: Many locale files have keys in a different order than English (e.g., saveFullScreenshotLabel at the end instead of after saveScreenshotTitle). When writing, always reorder to match English — this is expected and keeps diffs clean.
• Regional variants: Some language pairs have deliberate differences — do NOT copy one to the other:
  • es (Spain) uses "Añadir" vs es_CL (Chile) uses "Agregar"
  • pt_PT uses "ficheiro/ecrã/etiquetas" vs pt_BR uses "arquivo/tela/tags"
  • fr uses "enregistrés" vs fr_CA uses "sauvegardés"
  • zh_CN (Simplified), zh_HK (Traditional HK), zh_TW (Traditional TW) each have distinct terminology
• Untranslated detection across batches: When parallelizing, include untranslated key info in every batch prompt, not just the batch containing the affected language — the detection step should identify all issues upfront before dispatching agents.
• Batch size: 7 batches of 4-5 languages works well for ~34 locales. Each agent completes in ~3-4 minutes.