git:20260917.0ba518d to git:20260917.fd61ccf

---

name: sync-l10n

description: Bring the app string catalog in step with the code at release time - translate new UI copy with the project glossary, remove catalog entries that no code uses, and triage string literals that look like unlocalized UI copy into the baseline (exempt or debt). Run as part of release prep, or on demand when the user asks to sync translations or localization. Nothing in everyday work depends on it.

---

# Sync L10n

Prowl localizes its UI (Simplified Chinese today). Everyday work is **not** blocked by

translations: a developer writes localizable English copy and moves on. This skill does the

catch-up **once per release**, so every release ships with a complete translation of the

copy the compiler can see, and every new suspicious literal has a recorded decision.

Read these first:

- `docs-ai/070-app-localization/000-plan.md` — the design and why it works this way.

- `docs-ai/070-app-localization/glossary.md` — the vocabulary. **Follow it for every value.**

All edits to the catalog and the baseline go through `scripts/localization.py`. Do not edit

`supacode/Localizable.xcstrings` or `scripts/localization_baseline.json` by hand: the script

validates placeholders and keeps the catalog in the exact format Xcode writes.

## Guiding principles

- **Translate what is new. Leave what exists.** Do not reword a finished translation unless

it is wrong or breaks the glossary. Low churn keeps the diff reviewable.

- **Every suspect gets a decision.** Localize it, exempt it with a category, or record it as

debt. Never make the audit pass by loosening the heuristics.

- **Prefer a rule over a list.** When a whole file or a call pattern is not UI (a new CLI

handler, a new logger), add an `exemptPaths` or `exemptLinePatterns` rule. Rules absorb

years of growth; per-literal entries do not.

- **Ask when the meaning is not clear.** A wrong exemption hides UI copy for good. Collect the

unclear suspects and ask the user once, with the location and your best guess for each.

large refactor inside a release.

## Steps

1. **Build and audit.** `$SCRATCH` is any temporary directory outside the repository.

```bash

make build-app

python3 scripts/localization.py audit --json > "$SCRATCH/l10n-audit.json"

```

```bash

```

```json

{

"Stop Host": {"zh-Hans": "停止主机"},

"Resetting “%@” restores %@.": {"zh-Hans": "重置“%1$@”会恢复 %2$@。"},

"Toggle Canvas": {"zh-Hans": "切换画布", "manual": true},

"%@:%@": null

}

```

```bash

python3 scripts/localization.py apply "$SCRATCH/l10n-new.json"

```

- Translate into **every** language the catalog uses (`untranslated` names the language).

- `null` means "do not translate": a key that is only placeholders, punctuation, or a

sample value such as `XXXX-XXXX`.

```bash

```

```bash

```

```bash

make check

```

```

## L10n Sync

Translated: <n> new, <n> updated · Removed: <n> unused · Marked manual: <n>

Suspects: <n> localized, <n> exempt (<categories>), <n> debt, <n> rules added

Debt: <before> → <after>

### Needs human decision

- <literal> — <location> — <your guess and why you are not sure>

```

## Making copy localizable

| Situation | Write |

| --- | --- |

| Literal passed straight to SwiftUI | `Text("…")`, `.help("…")`, `Button("…")` — already localizable |

| The code needs a `String` (state, an alert, a toast) | `String(localized: "…")` |

| A helper takes copy as a parameter | Type the parameter `LocalizedStringKey` or `LocalizedStringResource`, not `String`. Do not keep a `String` overload: a literal selects it |

| A view-only helper returns copy | Return `LocalizedStringKey` |

| Long copy | One multi-line literal with `\` line continuations. `"a " + "b"` is a `String` and is never localized |

| The title is only known at run time | `LocalizedStringResource(runtimeKey:)`, and mark the catalog entry `manual` |

| Data, not copy (a branch name, a path) | `Text(verbatim:)` |

SwiftLint's `void_function_in_ternary` can misfire on `flag ? String(localized: "a") :

String(localized: "b")` inside a `switch` expression. Use `if`/`else` there.

## Committing

- Stage only `supacode/Localizable.xcstrings`, `scripts/localization_baseline.json`, the

glossary when it changed, and the Swift files you made localizable. Never `git add .`.

- **As part of release prep** (the `release` skill, on `main`): commit as its own commit before

the version bump and tag, for example `git commit -m "Sync localization for <VERSION>"`.

`release.sh` aborts on a dirty tree, and the commit must be an ancestor of the tag.

- **Standalone run** on a branch: open a PR that targets `onevcat/Prowl`.

## Adding a language

Add the first translation in the new language with `apply`. From then on the audit requires

that language for every entry. Add `docs-ai/070-app-localization/glossary-<language>.md`

before you translate in bulk.