{
  "id": "page:library-internationalization",
  "_kind": "Page",
  "_file": "wiki/library/internationalization.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "internationalization (Library)",
    "displayName": "internationalization (Library)",
    "slug": "library/internationalization",
    "articlePath": "wiki/library/internationalization.md",
    "article": "\n# internationalization\n\nThe first **internationalization / i18n** specialization in the library. It owns the full\nagentic localization pipeline — carrying a source codebase from hardcoded strings through\nper-locale translation to a policy-gated production release — with per-locale parallel\nfan-out and human approval on every action that commits spend or ships a locale to users.\nNo i18n specialization existed anywhere in `library/` before this one.\n\n## Flagship process: localization-lifecycle\n\n`localization-lifecycle.js` (`@process internationalization/localization-lifecycle`) walks\none source root through the whole lifecycle:\n\n| Phase | What happens |\n|---|---|\n| 0 | `kipRecall` at start — glossary terms + prior locale issues thread into every translate and QA task (`kipEnabled`, kind `i18n-glossary`) |\n| 1 | String extraction & externalization (`i18n.extract-externalize`) — hardcoded literals rewritten to resource keys, key hygiene enforced (stable dotted keys, dedup, NO runtime concatenation, ICU placeholders/plurals), source catalog + `keyHygiene` report written |\n| 2 | Conditional `translation-vendor-spend` policy gate — raised **once** when any target locale routes to a human-vendor tier; `i18n.commit-vendor-spend` executor runs only on `approved===true` |\n| 3 | Per-locale parallel pipeline via `ctx.parallel.all` — (3a) `i18n.translate-locale` per `tierRouteFor(locale).route`, (3b) adversarial `internationalization.translation-qa.<locale>` gate, (3c) executed `i18n.regression-sweep` (pseudo-locale + RTL + length-expansion) |\n| 4 | Per-locale `locale-publish-approval` policy gate — raised only for locales that PASSED both 3b and 3c; `i18n.publish-locale` executor runs only on `approved===true` |\n| 5 | `kipAssert` at close — glossary additions + per-locale QA outcome, regression outcome, and release decision |\n\n**Inputs:** `{ sourceRoot (required, default '.'), sourceLocale?='en-US', targetLocales (required non-empty BCP-47 tags — each must resolve in LOCALE_TIERS), vendor? {name, contactRef} (required when any target routes to a human-vendor tier), glossary? {terms:[{source,target?,doNotTranslate?,note?}]}, resourceDir?='artifacts/i18n/locales', maxFixAttempts?=2, kipEnabled?=true, kipDir?='.a5c/kip', kipModel?='sonnet', artifactsDir? }`\n\n**Outputs:** `{ success, extraction, locales, gatedActions, glossaryAdditions, kipFactsAsserted, artifacts, metadata }` — `success = extraction ok && at least one locale released && every released locale had approved===executed`. Blocked locales are surfaced honestly in `metadata.localesBlocked`, never silently dropped.\n\n## LOCALE_TIERS routing table\n\nA frozen (`Object.freeze`) routing table keyed by BCP-47 tag, styled on\n`incident-lifecycle.js` `SEVERITY_ROUTING`. `tierRouteFor(locale)` returns the frozen\nentry and **throws** on any locale absent from the table — there is **no default tier**\n(fallbacks forbidden). `isRtl(locale)` derives directionality from `RTL_LOCALES`\n(`['ar','he','fa','ur']`) and throws on an empty/invalid tag. Operators extend the table\nper product.\n\n| locale | tier | route | vendorSpendGated | rtl |\n|---|---|---|---|---|\n| `ar-SA` | tier1 | human-vendor | true | yes |\n| `de-DE` | tier1 | human-vendor | true | no |\n| `es-ES` | tier2 | machine-plus-human-review | false | no |\n| `fr-FR` | tier1 | human-vendor | true | no |\n| `he-IL` | tier2 | machine-plus-human-review | false | yes |\n| `ja-JP` | tier1 | human-vendor | true | no |\n| `nl-NL` | tier3 | machine-only | false | no |\n| `pt-BR` | tier2 | machine-plus-human-review | false | no |\n\n`route` is one of `human-vendor` | `machine-plus-human-review` | `machine-only`.\n`vendorSpendGated:true` means the locale's translation contributes to the\n`translation-vendor-spend` gate. `LENGTH_EXPANSION_BUDGET` (also frozen) supplies the\nper-locale length-expansion threshold used by the regression sweep (German expands most at\n1.35; CJK contracts, e.g. `ja-JP` 0.6); it ships an explicit documented `default` entry.\n\n## Policy-gated actions\n\nAll approvals go through `routedBreakpoint`; for both policy-gated actions the\n`breakpointId` **equals** the actionId and tags are `['policy-gated','internationalization']`.\nFail-closed: the executor task runs **only** on `approved===true` — a rejection is honored,\nrecorded, and never worked around (no machine-substitution fallback).\n\n| actionId | expert | when | fail-closed behavior |\n|---|---|---|---|\n| `translation-vendor-spend` | budget-owner | conditional — raised once when `vendorLocales` (any target whose `LOCALE_TIERS` entry has `vendorSpendGated:true`) is non-empty; requires `inputs.vendor` (throws if absent) | executor runs only on `approved===true`; on rejection the vendor-tier locales are recorded **blocked-for-spend** and NOT machine-substituted; skipped entirely (`required:false`) when no vendor tier is targeted |\n| `locale-publish-approval` | localization-lead | per locale — raised only for locales that PASSED both the translation-QA gate and the regression sweep | executor runs only on `approved===true`; rejection leaves the locale unreleased (`approved:false`/`executed:false`); blocked locales are recorded `required:false` and never reach the gate |\n\nAdditional (non-gated) breakpoint on the surface:\n\n- `internationalization.translation-qa.<locale>.gate-escalation` — raised internally by the\n  `adversarialGate` combinator per locale on fix-budget exhaustion (expert `owner`,\n  combinator-fixed). The process does not re-declare it; an escalation reject blocks that\n  locale.\n\n`outputs.gatedActions` records **every** decision — `{ actionId, required, approved,\nautoApproved, response, executed }` — including auto-approvals (recorded raw from the\nBreakpointResult) and skipped conditional gates (`{ required:false, approved:false,\nautoApproved:false, response:null, executed:false }` — never omitted). `publishLocale` is\nkeyed per-locale. `metadata.breakpointsHit` logs every raised breakpointId in order.\n\n## Quality bar\n\n- **adversarialGate translation-QA with executed evidence** — three independent critics\n  (`glossary-conformance-critic`, `placeholder-integrity-critic`,\n  `cultural-back-translation-critic`) fanned out in parallel, all distinct from the\n  `localization-translator`. Critics must RUN an executed back-translation diff and a\n  programmatic source-vs-target placeholder diff; file-read citations alone do not satisfy\n  the gate, and `passed:true` with an empty evidence array is a protocol failure enforced by\n  the combinator.\n- **Executed regression sweep** — `i18n.regression-sweep` EXECUTES a pseudo-localization\n  render, an RTL mirror check (`isRtl`-driven), and a length-expansion measurement vs\n  `LENGTH_EXPANSION_BUDGET`; `evidence` is `minItems:1` and the orchestrator honors\n  `passed:true` only with non-empty executed evidence.\n- **Bounded fix loop** — the shared `gateFixerTask` edits the locale bundle for up to\n  `maxFixAttempts` rounds, then the combinator escalates to the owner.\n- **No fallbacks** — an unknown locale tier throws (`tierRouteFor`), an unknown locale\n  directionality throws (`isRtl`), an empty `targetLocales` throws, a vendor-tier locale\n  without `inputs.vendor` throws **before** the spend gate, and a gate-unapproved release is\n  never executed via an alternate path. A locale that fails its QA gate (incl. escalation\n  reject) or its regression sweep is BLOCKED and surfaced in `metadata.localesBlocked`.\n\n## kip integration\n\n`kipRecall` at start (topic: glossary terms and prior locale issues for the source targets,\nkind `i18n-glossary`) and `kipAssert` at close — confirmed/added glossary terms\n(`term:<source>` --localizes-to--> `<target>` `{locale}`), per-locale QA outcome\n(`locale:<tag>` --qa-gate-outcome-->), regression outcome, and release decision — per\n`shared/skills/kip-librarian`. An empty store is a fresh brain, never an error; assert\nfailures are reported by the librarian task, never swallowed.\n\n## Usage\n\n```bash\nbabysitter run:create \\\n  --process library/specializations/internationalization/localization-lifecycle.js \\\n  --inputs '{\n    \"sourceRoot\": \".\",\n    \"sourceLocale\": \"en-US\",\n    \"targetLocales\": [\"de-DE\", \"ja-JP\", \"ar-SA\", \"nl-NL\"],\n    \"vendor\": { \"name\": \"Acme Localization\", \"contactRef\": \"vendor@acme-loc.example\" },\n    \"glossary\": {\n      \"terms\": [\n        { \"source\": \"Dashboard\", \"target\": \"Übersicht\", \"note\": \"de-DE product term\" },\n        { \"source\": \"Acme\", \"doNotTranslate\": true }\n      ]\n    },\n    \"resourceDir\": \"artifacts/i18n/locales\",\n    \"maxFixAttempts\": 2\n  }'\n```\n\n`targetLocales` above mixes tiers deliberately — `de-DE`/`ja-JP`/`ar-SA` are human-vendor\n(so the `translation-vendor-spend` gate fires and `vendor` is required), `ar-SA` is RTL (so\nthe regression sweep runs a mirror check), and `nl-NL` is machine-only.\n\n## Files\n\n- [`localization-lifecycle.js`](./localization-lifecycle.js) — the flagship process (the\n  `i18n.*` Style-A agent tasks + the frozen `LOCALE_TIERS`/`RTL_LOCALES`/\n  `LENGTH_EXPANSION_BUDGET` routing tables with throwing lookups + orchestration).\n- Combinators: [`../common-utilities/routed-gate-combinators.js`](../common-utilities/routed-gate-combinators.js)\n  — `routedBreakpoint`, `adversarialGate`, `gateFixerTask`, `kipRecall`, `kipAssert`.\n```\n",
    "documents": [
      "specialization:internationalization"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-internationalization",
      "to": "specialization:internationalization",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-internationalization",
      "kind": "contains_page"
    }
  ]
}