Translate New Strings

Translate new strings

Canonical recipe for getting Localizable.xcstrings back to a fully-translated state after adding, changing, or invalidating keys. This skill drives the existing scripts/translate_catalog/ pipeline in subset mode.

Definition of done: python3 scripts/check_translations.py exits 0. That is the same check lefthook.yml runs on pre-push, so a clean exit here guarantees the push will pass the translation gate.

Hard rules

• Never write ad-hoc Python (python3 -c "..." heredocs, throwaway tmp/*.py) to slice source.json, filter outputs, add catalog keys, remove catalog keys, or post-process anything. Every operation in this pipeline has a flag on one of the existing scripts. If you find yourself reaching for python3 -c, stop — the right move is to extend one of the existing scripts (or add a new primitive to scripts/translate_catalog/) so the workflow stays disciplined and the permission surface stays narrow. Treat the urge to write inline Python as a signal that this skill is missing a primitive.
  • Adding keys → add_keys.py (see Step 0a)
  • Updating English source text → update_keys.py (see Step 0b)
  • Renaming keys → rename_keys.py (see Step 0c)
• Never skip the pre-push checks at the end. Treat anything less than exit 0 from check_translations.py as not-done and loop back.
• All commands run from repo root. Paths in this skill are repo-relative.
• Register notes are intentionally duplicated — keep them in sync, don't DRY them. The per-locale formality guidance in REGIONAL_NOTES (scripts/translate_catalog/dispatch_prompts.py) deliberately overlaps with CULTURAL_NOTES in the metadata pipeline only on the formality decision per language (issue #173, closed without consolidation). If you change a language's formality decision (e.g. de "du"→"Sie") here, mirror it in CULTURAL_NOTES; wording may differ, the formality call must not. Don't try to merge the two maps.

Recipe

Pre-flight — clear stale pipeline outputs

Before anything else, clear any per-locale leftovers from a previous run. validate.py and merge.py read every file in tmp/translate-outputs/ (not just this run's manifest), so stale files silently contaminate the run — dispatch_prompts.py only cleans the manifest's locales, this clears any others too.

python3 scripts/pipeline_tmp.py status translate   # inspect leftovers
python3 scripts/pipeline_tmp.py clean translate    # clear them (allowlisted; no prompt)

0. Catalog maintenance (before translating)

Run whichever of these applies before Step 1. All three scripts are pre-approved in .claude/settings.json and will not prompt. Do not use inline Python for any of these operations.

Both invocation forms shown below work without prompting: the heredoc form (no temp file, preferred for small batches) and the temp-file form (useful for large batches). For the temp-file form, write JSON to tmp/<anything>.json — the Write(tmp/**) and Bash(python3 scripts/translate_catalog/<script>:*) permissions are both pre-approved.

0a. Add new keys

Use when String(localized: "key.name") exists in Swift but the key is not yet in Localizable.xcstrings. Inserts the key with en.state: translated; leaves all other locales absent so extract.py --missing flags them automatically.

python3 scripts/translate_catalog/add_keys.py - << 'EOF'
{
  "my.feature.title": {
    "comment": "Title shown on the My Feature screen",
    "value": "My Feature"
  }
}
EOF

Input shape: { "key": { "comment": "...", "value": "English string" } }. Existing keys are skipped unless --force is passed.

0b. Update English source text

Use when the displayed English text for an existing key changes (copy edit, wording change, etc.). Updates the en value and marks every existing non-en translation needs_review so the full re-translation round-trip runs automatically via Step 1.

python3 scripts/translate_catalog/update_keys.py - << 'EOF'
{
  "my.feature.title": {
    "value": "Revised English text",
    "comment": "Updated hint (optional — omit to keep existing comment)"
  }
}
EOF

Input shape: { "key": { "value": "New English string", "comment": "..." } }. comment is optional. Keys absent from the catalog are skipped with a warning.

0c. Rename keys

Use when a key identifier changes (e.g. a UI element moved to a different screen or section and the key path should reflect that) but the displayed text and all translations stay exactly the same. Copies the full entry — comment, extractionState, every locale translation — from the old key to the new key, then removes the old key. No re-translation is needed after a pure rename.

python3 scripts/translate_catalog/rename_keys.py - << 'EOF'
{
  "old.screen.featureName": "new.screen.featureName"
}
EOF

Input shape: { "old.key": "new.key" }. Supports --dry-run to preview changes and --force to overwrite an existing new key.

After renaming, update the Swift call sites to use the new key, then run check_source_strings.py (Step 5) to confirm no stale references remain. No need to run extract.py --missing unless you also changed the English text.

0d. Convert count strings to plurals

Use when a string interpolates a count (%lld) and reads wrong at 1 (e.g. "1 logged expenses"). Converts the key's English to a CLDR variations.plural block and clears the non-en locales so they re-translate as plurals (each locale gets the categories it needs).

python3 scripts/translate_catalog/pluralize_keys.py - << 'EOF'
{ "my.count.key": { "one": "%lld item", "other": "%lld items" } }
EOF

other is required. Then run Step 1 onward — the pipeline emits/validates/merges plural keys end to end (subagents return a { "key": {"one": …, "other": …} } object for plural keys per rule 7 in the template). The pre-push gate (check_translations.py) already validates plural variations.

0e. Force re-translation when a glossary term changed (English unchanged)

Use when the English source text is unchanged but the translation must change — most commonly when a glossary term was re-translated (e.g. "Carry-Over" stopped being a protected English term and gained per-locale renderings), so every key that embeds that term must flow through translation again. update_keys.py is the wrong tool here (it's for English changes and rewrites the en value); use invalidate_keys.py, which marks the keys' non-en locales needs_review and never touches en.

python3 scripts/translate_catalog/invalidate_keys.py --keys-file tmp/keys.txt
# or
python3 scripts/translate_catalog/invalidate_keys.py --keys k1,k2,...

Supports --dry-run. Then run Step 1 onward — extract.py --missing re-emits the invalidated keys and the normal dispatch → validate → merge round-trip re-translates them with the updated glossary term injected.

1. Detect what needs translating

python3 scripts/translate_catalog/extract.py --missing

This writes:

• tmp/translate-inputs/source.json — the union of all keys that are missing or stale in at least one locale, with English source + comment + format specifiers.
• tmp/translate-inputs/manifest.json — {locale: [keys...]} telling you exactly which locales need work and for which keys.

If the script reports "No missing or stale translations found", you are done — skip to step 5 to confirm.

2. Compose per-locale prompts

python3 scripts/translate_catalog/dispatch_prompts.py

This writes one ready-to-dispatch prompt per locale to tmp/translate-prompts/{locale}.md. Each prompt has {LOCALE_NAME}, {LOCALE_CODE}, {REGIONAL_NOTE}, {GLOSSARY}, and {SOURCE_JSON} (sliced to just that locale's missing keys) already substituted.

{GLOSSARY} is filled automatically from scripts/translate_catalog/glossary.json: for each locale, dispatch_prompts.py injects the agreed translations of any glossary term that appears in that slice, so new strings stay terminologically consistent with the rest of the app (rule 6 in the template tells the subagent how to use them, including for sub-parts of a string). Nothing to do here — it just works when the glossary is populated.

By default this also deletes any stale tmp/translate-outputs/{locale}.json files for the locales in the manifest, so step 3's subagents start from a clean slate and step 4's validate.py --subset doesn't trip on leftover keys from a prior run on a different branch. Pass --no-clean only if you're manually iterating on one locale's output and want to preserve the others.

3. Translate each locale's slice

Cross-tool execution. On Claude Code, dispatch one translation-locale subagent per locale in parallel (below). On Cursor or any tool without a subagent primitive, run the same step inline and serially: for each tmp/translate-prompts/{locale}.md, read it, produce the translation JSON yourself, and write tmp/translate-outputs/{locale}.json — then continue to step 4. Same scripts, same gates, same result. Canonical: AGENTS.md > Cross-cutting concerns > Running the translation pipelines.

Claude Code — one translation-locale subagent per locale, in parallel

For every tmp/translate-prompts/{locale}.md that exists, invoke an Agent with:

• subagent_type: translation-locale (defined in .claude/agents/translation-locale.md)
• A short dispatch prompt that tells the subagent which prompt file to read and where to write its JSON output. Example:

  Read /abs/path/tmp/translate-prompts/ja.md and follow the rules in it. Write the resulting JSON object (nothing else) to /abs/path/tmp/translate-outputs/ja.json.

The subagent definition restricts the subagent to Read + Write only, defaults to haiku, and encodes the "JSON only, this file only" contract. Do not pass subagent_type: general-purpose — the narrower agent is what makes the dispatches auto-approvable in this project's .claude/settings.json.

Send all subagent calls in a single message so they run concurrently. With 49 locales × small key counts this typically finishes in well under a minute.

The subagent's prompt already contains every translation rule — placeholder preservation, tone, regional dialect notes, JSON-only output. Do not modify it.

4. Validate, then merge

python3 scripts/translate_catalog/validate.py --subset

--subset mode only checks the keys actually present in each output file (the manifest slice), so partial outputs are first-class. If any locale fails:

• Re-read its prompt, re-dispatch a fresh subagent (often the same prompt works on retry), then re-validate.
• Format-specifier mismatches are the most common failure — the subagent's translation dropped or duplicated a %@ / %lld. Retry usually fixes it.

Once validate.py --subset exits 0:

python3 scripts/translate_catalog/merge.py

Merge only writes catalog entries for keys present in the output files, and refuses to overwrite a non-empty entry with an empty value, so existing translations are safe. For each key it merges, merge.py also promotes that key's English source from state: "new" → "translated" (Xcode auto-extraction lands new keys as "new"). This means a key that went through this pipeline will not trip the NEW [en] (source) gate in step 5 — the previous manual add_keys.py --force + re-merge dance is no longer needed for pipeline keys.

Fast path — steps 4 and 5 in one shot. Once the subagents have written tmp/translate-outputs/, run the deterministic tail as a single command (every sub-command is individually allowlisted, so it never prompts):

python3 scripts/translate_catalog/validate.py --subset \
  && python3 scripts/translate_catalog/merge.py \
  && python3 scripts/check_translations.py \
  && python3 scripts/check_source_strings.py

If validate.py --subset fails for a locale, re-dispatch that locale's subagent and re-run the chain. Don't split these into four separate tool calls — that's slower and was the source of past friction.

4b. Keep the glossary current (after merge)

New features often introduce terminology that now recurs across keys. Keep the glossary (scripts/translate_catalog/glossary.json) in step with it:

python3 scripts/translate_catalog/glossary_sync.py --detect

This is deterministic (no LLM). It detects high-confidence new terms — an English string now reused across ≥2 keys but not yet in the glossary — and writes them to tmp/glossary/terms.json; more ambiguous frequent words go to tmp/glossary/candidates_review.json for you to skim. If it reports new high-confidence terms, add them to the glossary (Opus):

python3 scripts/translate_catalog/glossary_build.py --dispatch
# fan out one glossary-locale (Opus) agent per tmp/glossary/prompts/{locale}.md, in a single
# message; each writes tmp/glossary/outputs/{locale}.json (see the audit/glossary docs)
python3 scripts/translate_catalog/glossary_build.py --merge

--merge appends to glossary.json (it never drops existing terms). Skip this step entirely if --detect reports nothing new. The fuller glossary build/rebuild flow lives in scripts/translate_catalog/README.md.

5. Authoritative pre-push gate

python3 scripts/check_translations.py
python3 scripts/check_source_strings.py

Both are run by lefthook.yml on pre-push.

• check_translations.py is the definition of done for this skill. It walks the catalog (not the per-locale output files), so it catches anything that didn't actually merge in correctly. If it reports missing/stale (key, locale) pairs:
  • Run extract.py --keys k1,k2,... for just those keys, or re-run --missing.
  • Loop back to step 2.
• check_source_strings.py catches hard-coded Text("English string") in Swift files. A failure here means there's an un-keyed string in production code — fix that first (add to xcstrings, then re-run this skill), since untranslated keys are downstream of un-keyed strings.
• NEW [en] '<key>' (source) means the key's English source state is still "new" (Xcode-extracted, not yet reviewed). For keys you just translated this is now auto-resolved by merge.py (see step 4). It can still surface for a key whose 49 locales were already complete (so nothing merged) but whose en stayed "new" — in that rare case run extract.py --keys <key> then the step-4 fast-path chain, or re-run merge.py (the existing tmp/translate-outputs/<locale>.json are reused and the en promotion fires). Do not hand-edit the catalog.

If check_translations.py reports keys that exist in the catalog but no longer have a Swift reference (i.e. the code dropped the String(localized: ...) call), those keys are orphaned. Remove them with:

python3 scripts/translate_catalog/remove_keys.py --keys k1,k2,...
# or
python3 scripts/translate_catalog/remove_keys.py --keys-file path/to/keys.txt

This deletes every locale entry for those keys cleanly. Use --dry-run first to see what would be removed.

6. Build + test

Standard four-step from AGENTS.md:

make format && make lint-fix && make build && make test

7. Cleanup — offer to clear tmp working files

Once check_translations.py is green, offer to clear this pipeline's gitignored tmp files. Ask first (the intermediate JSON is handy if the user wants to inspect a locale); on a yes:

python3 scripts/pipeline_tmp.py clean translate

Subagent prompt invariants

The prompt file generated by dispatch_prompts.py is the single source of truth. Subagents are told to:

1. Preserve every format specifier exactly (count and form; order may change for grammar).
2. Use the comment field for context.
3. Match Apple's first-party iOS app voice for the target locale.
4. Leave Wren, iCloud, and other Apple-untranslated proper nouns in English.
5. RTL locales (ar, he, ur): never start a sentence or UI string with a Latin brand token (Wren, iCloud). In RTL rendering a Latin-initial string pops to the visual end of the line. Lead with a native word; the brand can follow mid-sentence.
6. Output only the JSON object — no markdown fences, no prose.

If you find yourself wanting to "remind" the subagent of one of these rules in the dispatch message, instead fix PROMPT_TEMPLATE.md so the rule survives across runs.

When to fall back to full backfill

This skill is the right tool when keys have been added/changed for a feature. It is not the right tool when:

• Changing the translation model and wanting to regenerate every existing translation.
• Seeding a brand-new catalog from scratch.
• Recovering from a corrupted catalog.

For those, see "Full backfill" in scripts/translate_catalog/README.md.

File layout reference

scripts/translate_catalog/
  locales.py            # LOCALES list + LOCALE_NAMES
  add_keys.py           # Step 0a: register new en keys; JSON file or stdin
  update_keys.py        # Step 0b: update en source text + invalidate translations; JSON file or stdin
  rename_keys.py        # Step 0c: rename keys preserving all translations; --dry-run; JSON file or stdin
  extract.py            # --missing | --keys | --keys-file | (no flags = all)
  dispatch_prompts.py   # manifest + template → tmp/translate-prompts/; cleans stale outputs by default
  validate.py           # --subset for partial outputs
  merge.py              # --keys filter; rejects empty values
  remove_keys.py        # --keys | --keys-file; deletes orphaned keys with all locale entries
  PROMPT_TEMPLATE.md    # subagent prompt template
  README.md             # script reference

scripts/
  check_translations.py    # authoritative pre-push gate
  check_source_strings.py  # hard-coded Text("...") detector

.claude/agents/
  translation-locale.md    # subagent definition used by step 3 (Read+Write only)

tmp/
  translate-inputs/source.json
  translate-inputs/manifest.json
  translate-prompts/{locale}.md
  translate-outputs/{locale}.json