l10n Sync updates existing translations from an English source without treating documentation or localization files as unstructured text. It plans changes first, applies translation only where needed, repairs safe structural drift, and verifies the result before handoff.
The workflow covers both Markdown documentation and the flat JSON bundles commonly used by VS Code extensions and modern localization tooling.
Supported source families
| English source | Existing targets |
|---|---|
README.md |
README_<LANG>.md files |
package.nls.json |
Localized package.nls.<lang>.json siblings |
bundle.l10n.json |
Localized bundle.l10n.<lang>.json siblings |
Another flat X.json |
Existing localized files in the same family |
File suffixes determine the target languages. The bundled language map can be extended and does not limit the workflow to the translations already present in the repository.
Incremental and full modes
Incremental mode uses Git history to identify Markdown blocks that changed in the English source. Unchanged translated blocks remain untouched, which keeps diffs smaller and reduces opportunities for accidental drift.
Full mode handles a new translation, a target whose structure no longer aligns with the source, or an existing translation when usable Git history is unavailable. It retranslates the necessary Markdown and then runs the same repair and verification pipeline.
JSON always follows a structured block workflow, whether translating only keys whose English values changed or performing a full pass. Keys are matched to the English source, plain string values are translated, and structured values are copied verbatim. Target JSON is not hand-edited as an improvised sequence of text replacements.
The safety pipeline
The bundled Python tool provides plan, merge, apply, repair, and verify operations. Planning establishes the exact target and mode. Applying writes the translations provided in results.json. Repair restores structural elements that can be recovered deterministically, and verification checks the final file against the source.
The checks protect code spans, URLs, placeholders, HTML, tables, JSON validity, and key order. They are designed to catch syntactically valid translations that would still break the consuming documentation or application.
Boundaries and guarantees
l10n Sync updates existing target files unless the user explicitly names a new one. It defaults to one language at a time so each result can be reviewed clearly; parallel language agents are used only when requested.
The repair step is structural, not magical. If a target is severely unrelated to its source, the correct response is a full translation rather than an attempt to reconstruct arbitrary corruption. Likewise, nested JSON objects are outside the translator’s scope: only plain strings in flat localization bundles are translated.
