Generated from
cat-harness/library/processes/multi-locale-translation.bpmnbygen-processes-viz.ts— do not edit here. All processes · cat-harness processes
Multi-locale translation
Process_MultiLocaleTranslation · advisory · 13 step(s)
Translate one or more layers into several locales at once, as a team: one source-language lead, one translator per locale, an untainted round trip, and the owner’s merge window. The result is unofficial, on main, and kept current by a watcher.
You are in this process when more than one locale is being produced from the same source at the same time. translation-workflow is the machine half for one catalogue and human-translation-workflow is the path to an official, signed-off translation; this process is the team around them. It extracts ONCE: every locale starts from the same templates, merged to main in one source PR before any locale begins, and no translator re-extracts. Each locale then lands as its own PR to main, never into the source branch, and a source PR’s branch receives nothing after it merges.
Two things are never done in a translation: fixing the source (a source-text error is reported as one issue to the lead), and editing a FHIR resource inline (terms go into one CodeSystem supplement per locale). Officiality is not decided here: every catalogue is written unofficial, and a person makes it official through human-translation-workflow.
How it connects
- Called by: Publish a web app — declared, translated, built at its own route
- Calls: Translation round trip (untainted)
- Presented on: no docs page section shows this diagram
- Running instances: none recorded
Lanes — who acts
| lane | role | what it does here |
|---|---|---|
| Owner | user | Decides which layers and locales are translated, and when locale PRs may be merged. The merge window set here binds the lead’s merge step and the refresh watcher alike. Official sign-off is also this person’s, and is a separate process. |
| Source-language lead | translation-source-lead | The one party that touches the source. It extracts every template once, merges that source PR first, collects source-text errors into one issue, validates and merges each locale PR inside the owner’s window, and keeps the watcher that runs translation-refresh. |
| Locale translator (one per locale) | locale-translator | One lane for every locale: each step here runs once per locale, in parallel, and each locale’s work is its own branch and its own PR. A translator starts from the merged templates, never from its own extraction, and reports a source error rather than translating around it. |
Steps
Every one of the 13 step(s) is documented.
| step | lane | skill / sub-process | what it does |
|---|---|---|---|
Set locales, scope and merge windowTask_ML_Scope | Owner | — | Which layers, which locales, which assets (pages, diagrams, glossary, FHIR terms), and the window in which locale PRs may be merged. |
Extract every template onceTask_ML_Extract | Source-language lead | shared step GT_ExtractPottranslation-manager | Scan the source content and write the translatable strings to .pot files at the configured granularity: segment prose by paragraph, shield what must not be translated (math, code, labels, Lean companions) as placeholders, normalise whitespace, and extract metadata such as titles, alt text and captions. Tool: the translation_extract MCP tool. Once, for every locale: the .pot templates for the pages, the diagrams (translate-bpmn --extract) and the glossary schemes, each by the layer’s own extractor. A locale that would need a different template is a defect in the extraction, not a reason to extract again. |
Merge the one source PR to mainTask_ML_SourcePR | Source-language lead | translation-manager | All the templates in one PR to main, merged before any locale starts, so every translator branches from the same main. Once it has merged, its branch receives nothing more: a later fix to the source is a new PR. |
Schedule the refresh watcherTask_ML_Watcher | Source-language lead | translation-refresh | Schedule a fresh session that follows translation-refresh on each layer, so a template that moves after today is caught by its check failing, not by a reader. |
Translate one localeTask_ML_Translate | Locale translator (one per locale) | translation-manager | From the merged templates, with the locale term base: translations/<locale>/**.po, a translation-node manifest beside each (official: false, generatedBy: "agent", or "machine" where translation:candidates filled an empty entry with its first candidate, which stays fuzzy; no status.json), and the FHIR terms as CodeSystem supplements, all in one file for the locale rather than edits inside the resources. |
File the source errors as one issueTask_ML_SourceIssue | Source-language lead | translation-manager | One issue for every source-text error the translators found, each with its location and the reading the translator took. Never fixed in a translation: a fix to the source is a source PR, and the next refresh carries it to every locale. |
Run the deterministic gatesTask_ML_Gates | Locale translator (one per locale) | translation-manager | Template currency, catalogue coverage, placeholder, tag and URL preservation, officiality, kg:locale, and the locale’s supplements compiling with no SUSHI error and passing their structural checks. |
Untainted round trip on a sampleCall_ML_RoundTrip | Locale translator (one per locale) | calls Translation round trip (untainted) | The sample: every diagram label, the personas and scenarios, and a seeded random fraction of the rest. |
Check glossary consistencyTask_ML_Glossary | Locale translator (one per locale) | translation-manager | translation:glossary:check, against the layered term base: the normative reference glossaries first, then each layer in the order the index config lists it, the layer’s own glossary last and never overriding. A platform term found in text of another subject area is a sense check for a person, not a violation. |
Write the locale’s QA reportTask_ML_QAReport | Locale translator (one per locale) | translation-manager | One report per locale under test/results/translation-qa/: coverage, the gates, the round trip with its counts and every drift ruling, the glossary violations and sense checks, and the source errors reported. |
Open the locale PR to mainTask_ML_LocalePR | Locale translator (one per locale) | translation-manager | One PR per locale, based on and targeting main. Never into the source branch. |
Fix each drift on the PRTask_ML_FixDrift | Locale translator (one per locale) | translation-manager | Correct each string the adjudicator ruled drift, on the locale PR, and note the fix beside the ruling in the QA report. |
Validate and merge in the windowTask_ML_Merge | Source-language lead | translation-manager | Read each locale’s QA report, confirm the PR is green, and merge it inside the owner’s merge window. Outside the window it waits. |
Decisions
Every one of the 3 decision(s) is documented.
| decision | what decides it | branches |
|---|---|---|
Source-text error found?Gateway_ML_SourceError | Did translating show a mistake in the source text? Yes reports it to the lead; the translation still renders the source as it stands. | Yes → File the source errors as one issue No → Run the deterministic gates |
Gates pass?Gateway_ML_Gates | Answered by the gates’ own exit codes, never by reading their output. Yes only when every gate exits 0; a gate that exits 2 (could not determine) is a No. No fixes the catalogue, manifest or supplement and runs the gates again. | Yes → Untainted round trip on a sample No: fix, re-run → Translate one locale |
Drift ruled?Gateway_ML_Drift | Answered by the round-trip adjudicator’s recorded verdicts for this locale: did it rule any pair drift? Yes fixes each one on the locale PR before the lead merges it. A “could not dispatch” record is not No: the PR says the round trip was not verified. | Yes → Fix each drift on the PR No → Validate and merge in the window |