| name | syncing-translations |
| description | Synchronizes the host project's locale files against the source-of-truth English catalog — buckets entries into identical, fuzzy, and missing, auto-applies the configured categories, and gates the rest on user approval. Use when locale files drift behind the English catalog or translations need syncing. |
| allowed-tools | Read Edit Bash(node:*) |
Sync every locale file under locales/ against locales/en.json. By default, identical entries
are copied directly, while fuzzy and missing entries are reviewed first and applied only after
the user approves. The config can widen or narrow the auto-sync set — but widening it removes the
approval gate, never the review behind it: every fuzzy and every missing entry is reviewed
whatever the config says, and only an auto-applied identical entry skips the scoring. Never edit
locales/en.json.
Configuration
Read .i18n-sync.json at the repo root, once, before anything else. Its autoSync key is an
array drawn from identical, fuzzy, missing. Default: ["identical"]. A category in the
auto-sync set auto-applies; a category outside the set is gated on the user's approval.
An empty array [] is the fully gated mode: nothing applies without approval. An invalid value —
a non-array, an entry outside the three categories — means stop and report the invalid config
rather than guess, because a guessed policy silently substitutes behavior the repo did not
choose.
Three rules bound what "auto" means. Later steps cite these rules by number rather than
restating them:
- Review is the constant. Every entry is scored except an identical entry in the auto-sync
set — fuzzy and missing entries are always scored, and a gated identical entry is scored too,
because a gate without scoring would ask the user to approve blind.
- Of the scored entries, auto applies only a match score above 0.9. A lower score always
stops for approval, whatever the auto-sync set says — auto-sync removes the ceremony for clean
entries, never the safety net for doubtful ones.
- No
autoSync value makes a plural-form entry automatic. Plural rules vary by locale, so a
plural entry is always scored and always stops for approval.
Steps
- Bucket. Compare each locale file against
locales/en.json and bucket every entry as
identical (same key, same source text), fuzzy (same key, changed source text), or
missing (key absent from the locale). Present the three buckets as a table before touching
anything, alongside the resolved auto-sync set and its provenance.
- Auto identical entries. When
identical is in the auto-sync set, copy those entries
directly and re-run the comparison, because a copy that lands wrongly must surface now rather
than in the report. When identical is not in the set, tick this step as skipped — the
identical entries join step 3's scoring pool like every other entry.
- Score the remaining entries. Compute a match score for every entry step 2 did not apply,
and decide the Action column per entry by the three rules in Configuration:
auto
when the entry passes rule 1 (its category is in the auto-sync set), rule 2 (its score is
above 0.9), and rule 3 (it is not a plural form), approval for every other entry.
- Apply the auto rows. Apply them without asking — that is what the config chose, and rule 2
already kept every doubtful entry out of this set — one bucket at a time, re-running the comparison after each bucket, so a regression cleanly
identifies which bucket caused it.
- Approval gate. Stop and await the user's choice on every
approval row — every plural
entry lands here by rule 3 — because an entry applied without approval is a translation the
user never reviewed. After the user decides,
apply the approved entries one bucket at a time, as in step 4, then re-run it to confirm the
drift has cleared.
- Report. Summarize what was applied (auto versus approved) per bucket, what was deferred,
and every step the config emptied, ticked with a "skipped — why" note rather than silently
omitted. The changes stay uncommitted, because the user reviews the working tree before
committing.
