Generated from
cat-harness/library/processes/translation-refresh.bpmnbygen-processes-viz.ts— do not edit here. All processes · cat-harness processes
Translation refresh (watcher)
Process_TranslationRefresh · advisory · 11 step(s)
Keep every locale current after the source moves: detect, refresh the templates, merge them into each locale, translate only what is new or fuzzy, check it, and land one PR per layer on main.
You are in this process when the watcher scheduled by multi-locale-translation wakes, or when a template check has failed. It is the loop that process ends with. A fresh session can run it cold: the skill translation-refresh gives each step as a command, and each layer’s own AGENTS.md names what is particular to it. One run walks every layer in turn, and each layer with something to refresh gets its own PR.
A refresh never re-translates a finished string. Obsolete strings are kept as #~ entries, new ones arrive empty, and only new and fuzzy strings are translated, with the terms the term base already fixes. The round trip runs on the changed strings only.
Round-trip rulings are keyed by content: each is pinned by the hash of the msgid it judged (and of the msgstr), never by its position in the catalogue. So removing or reordering strings invalidates no ruling and needs no agent re-run. Once main no longer holds a removed string, its ruling is dropped mechanically by the prune step.
How it connects
- Called by: no call activity names this process
- Calls: Translation round trip (untainted)
- Names the
translation-refreshskill without calling this process: Multi-locale translation —activity-calls-skill-processasks whether each should be a call activity. - Presented on: no docs page section shows this diagram
- Skill:
translation-refresh - Running instances: none recorded
Lanes — who acts
Steps
Every one of the 11 step(s) is documented.
| step | lane | skill / sub-process | what it does |
|---|---|---|---|
Cold start: mount and attachTask_TR_ColdStart | Source-language lead (watcher) | translation-refresh | Lay down every pinned layer from each layer’s lock, as its AGENTS.md cold start says, and attach each repository the run will change. |
Detect what movedTask_TR_Detect | Source-language lead (watcher) | translation-refresh | translation:status --instance <root> for new, obsolete and fuzzy strings, and the instance’s template check. Either failing, or showing anything but zero, is a change. |
Refresh the templatesTask_TR_Templates | Source-language lead (watcher) | translation-refresh | Re-run the layer’s extractors, once for every locale: pages, diagrams, glossary schemes. |
Merge into each localeTask_TR_MergeLocales | Source-language lead (watcher) | translation-refresh | Merge each refreshed template into every locale’s catalogue: new strings arrive empty, changed ones fuzzy, and obsolete ones are kept as #~ entries, never deleted. |
Translate new and fuzzy onlyTask_TR_Translate | Locale translator | translation-manager | Only the empty and fuzzy entries, in every locale, with the terms the term base fixes. A finished string is not touched. Candidates for the empty and fuzzy entries may come first from translation:candidates (Tool translation-candidates: open engines, OPUS-MT and/or self-hosted LibreTranslate), recorded in <catalogue>.candidates.json; an empty entry also gets the first good candidate, fuzzy, until it is re-translated here or a person picks or accepts one on the review page. |
Re-run the gatesTask_TR_Gates | Locale translator | translation-manager | Officiality, catalogue coverage, translated links, kg:locale, translation:glossary:check, and the supplements compiling. |
Round trip on the changed stringsCall_TR_RoundTrip | Locale translator | calls Translation round trip (untainted) | The untainted round trip, with the sample restricted to the strings this run translated. |
QA report and one PR to mainTask_TR_Report | Locale translator | translation-manager | Write each locale’s QA report, then open one PR for the layer, based on and targeting main. |
Report source errors as one issueTask_TR_SourceIssue | Source-language lead (watcher) | translation-refresh | Any source-text error the translators found goes into one issue on the source, with its location. When there is none, this step writes nothing. |
Merge the PRTask_TR_Merge | Source-language lead (watcher) | translation-refresh | Merge the layer’s PR to main, then confirm the template checks pass on main. |
Prune the rulings of removed stringsTask_TR_PruneRulings | Source-language lead (watcher) | translation-refresh | Drop the round-trip rulings of strings main no longer holds, with the layer’s prune command (its AGENTS.md names it, by convention translation-qa:prune), once the PR is on main. Only a layer that keeps per-string rulings on an attestations state branch has one. Run it as a dry run first: it lists each ruling whose msgid main no longer holds but once did, and the indices it renumbers to catalogue order. Push the result (--write, then the state-branch push) only when the diff is purely dropped and renumbered rulings. It never changes or invents a verdict, and it keeps a ruling recorded ahead of a PR that has not merged. Never run it before the removal is on main: the state branch serves main too, and main would be left with strings that have no ruling. Nothing to prune is the usual result, and this step then writes nothing. |
Decisions
Every one of the 3 decision(s) is documented.
| decision | what decides it | branches |
|---|---|---|
Anything to refresh?Gateway_TR_Changed | Answered from the detection commands’ output: Yes when any template check fails or any count of new, obsolete or fuzzy strings is above zero. No ends the run for this layer. A command that exits 2 is neither: it is reported for the layer, and the run moves on. | Yes → Refresh the templates No → Current |
Gates pass?Gateway_TR_Gates | Yes only when every gate exits 0. No fixes the catalogue, manifest or supplement and re-runs the gates; an exit 2 is a No. | Yes → Round trip on the changed strings No: fix → Translate new and fuzzy only |
Merge-when-green, and all green?Gateway_TR_Window | Three facts, all read live: the layer’s AGENTS.md declares merge-when-green, every check on the PR is green, and the untainted round trip on the changed strings records no fail. Yes merges. No leaves the PR open and reports it to the owner; the default policy, open only, always answers No. | Yes → Merge the PR No → PR left open |