docs agent overwrote translated docs with english source strings

TL;DR

Restore the translations from git, then separate the agent's write targets: it may update source-locale files and translation templates, never finished translations. Add a locale guard that aborts the sync if it would write to a translated file.

The exact error

docs agent overwrote translations with english source

Steps

1. Assess the damage Diff the translation directories against the last good commit to list every overwritten file. Success check: You know exactly which translations were lost.

2. Restore from version control Check out the translation files from the last good commit. Success check: Translations are restored to their pre-overwrite state.

3. Separate write targets Configure the agent so its sync writes only source-locale files and message catalogs; translated files are read-only to it. Success check: The agent cannot write to translated files by construction.

4. Add a locale guard Before any docs write, check the target file's locale; abort with an error if it is a finished translation. Success check: Future syncs fail safe instead of clobbering.

When to use

• Use when an agent's docs sync destroys translations.
• Use when designing locale-aware doc pipelines.

When not to use

• Not for untranslated strings in the source (translation workflow problem).
• Not for machine-translation quality issues (different problem).

Why it happens

Translation files and source files often share names across locale directories, so a sync that walks the tree naively treats them as identical targets. The agent did what it was told; the pipeline gave it write access it should never have had.

Edge cases

The locale guard is cheap insurance: one path check before each write. Translation memory systems can also re-apply lost translations, but restoring from git is faster and exact.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SF3zQJkSDaTlQIIpCc30sg