Generated from cat-harness/library/processes/translation-refresh.bpmn by gen-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.

BPMN diagram: Translation refresh (watcher)

How it connects

Lanes — who acts

lanerolewhat it does here
Locale translatorlocale-translatorThe same position as in the first translation, now working on a delta: only the strings the merge left empty or fuzzy, in every locale, then the gates and the round trip over those strings.
Source-language lead (watcher)translation-source-leadOwns the watcher. It decides whether anything changed from the files, not from memory, refreshes the templates once for every locale, and merges the layer’s PR only where the layer declares merge-when-green, every check is green and the round trip records no fail.

Steps

Every one of the 11 step(s) is documented.

steplaneskill / sub-processwhat it does
Cold start: mount and attach
Task_TR_ColdStart
Source-language lead (watcher)translation-refreshLay 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 moved
Task_TR_Detect
Source-language lead (watcher)translation-refreshtranslation: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 templates
Task_TR_Templates
Source-language lead (watcher)translation-refreshRe-run the layer’s extractors, once for every locale: pages, diagrams, glossary schemes.
Merge into each locale
Task_TR_MergeLocales
Source-language lead (watcher)translation-refreshMerge 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 only
Task_TR_Translate
Locale translatortranslation-managerOnly 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 gates
Task_TR_Gates
Locale translatortranslation-managerOfficiality, catalogue coverage, translated links, kg:locale, translation:glossary:check, and the supplements compiling.
Round trip on the changed strings
Call_TR_RoundTrip
Locale translatorcalls Translation round trip (untainted)The untainted round trip, with the sample restricted to the strings this run translated.
QA report and one PR to main
Task_TR_Report
Locale translatortranslation-managerWrite each locale’s QA report, then open one PR for the layer, based on and targeting main.
Report source errors as one issue
Task_TR_SourceIssue
Source-language lead (watcher)translation-refreshAny 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 PR
Task_TR_Merge
Source-language lead (watcher)translation-refreshMerge the layer’s PR to main, then confirm the template checks pass on main.
Prune the rulings of removed strings
Task_TR_PruneRulings
Source-language lead (watcher)translation-refreshDrop 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.

decisionwhat decides itbranches
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

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev