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

BPMN diagram: Multi-locale translation

How it connects

Lanes — who acts

lanerolewhat it does here
OwneruserDecides 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 leadtranslation-source-leadThe 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-translatorOne 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.

steplaneskill / sub-processwhat it does
Set locales, scope and merge window
Task_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 once
Task_ML_Extract
Source-language leadshared step GT_ExtractPot
translation-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 main
Task_ML_SourcePR
Source-language leadtranslation-managerAll 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 watcher
Task_ML_Watcher
Source-language leadtranslation-refreshSchedule 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 locale
Task_ML_Translate
Locale translator (one per locale)translation-managerFrom 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 issue
Task_ML_SourceIssue
Source-language leadtranslation-managerOne 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 gates
Task_ML_Gates
Locale translator (one per locale)translation-managerTemplate 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 sample
Call_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 consistency
Task_ML_Glossary
Locale translator (one per locale)translation-managertranslation: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 report
Task_ML_QAReport
Locale translator (one per locale)translation-managerOne 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 main
Task_ML_LocalePR
Locale translator (one per locale)translation-managerOne PR per locale, based on and targeting main. Never into the source branch.
Fix each drift on the PR
Task_ML_FixDrift
Locale translator (one per locale)translation-managerCorrect 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 window
Task_ML_Merge
Source-language leadtranslation-managerRead 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.

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

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