odoo-i18n

name	odoo-i18n
argument-hint	[module(s)] [target-lang e.g. vi_VN]
description	This skill should be used when the user asks to translate one or more Odoo modules into any target language (default vi_VN), export .pot/.po, update translations, sync terminology, or audit cross-module term consistency. Fire on "translate this module", "export .pot / .po", "update the translation", "sync terminology", "đồng bộ thuật ngữ", "dịch module Odoo", "xuất .pot/.po", "cập nhật bản dịch", or any i18n / terminology-consistency ask for Odoo. Front door for ALL Odoo translation work and the ONLY dispatcher of the odoo-translator agent; also the i18n step other workflows dispatch into (forward-port, new module, bugfix). Non-destructive contract is load-bearing: re-exporting a .po from a fresh DB destroys 40-90% of existing msgstr, so translation MEMORY is always forwarded by merge, never regenerated. Requires a running Odoo instance; missing instance is a BLOCK. Route a one-line UI label fix to odoo-coding; a rendered-UI language check to odoo-ui-review

Role

i18n conductor for Odoo translation. Owns the .pot/.po lifecycle, the glossary, and the subagent lifecycle for translating a module or module scope onto a target Odoo series. Makes the orchestration decisions (phase model tier, when to stop for a human, when to dispatch the leaf translator) and delegates actual term translation to the odoo-translator agent.

The load-bearing belief: a translation is MEMORY to be forwarded, never regenerated. Re-exporting a .po from a database that has NOT loaded the existing translation overwrites it with empty msgstrs and silently destroys 40-90% of the human translation with a clean exit code. The non-destructive method: build a FRESH instance, LOAD the existing .po into it, re-export (which then reproduces the translation), then RECONCILE by a git-ops diff-review - adjudicate every removed/changed entry as correct or wrong before commit (no polib). A clean export + a green install is NOT proof the translation survived; only an adjudicated diff-review plus an Odoo -u reload proves it. Full non-destructive recipe (3-layer L1/L2/L3 + validation + glossary): references/i18n-recipe.md - the SSOT this skill and odoo-forward-port both point at.

Sole dispatcher (single source of truth for i18n fan-out). This skill is the ONLY component that launches the odoo-translator agent. Any other skill that needs a module translated, a .pot/.po exported/merged, or cross-module terminology audited routes that work HERE via the Skill tool instead of spawning the agent itself, so the non-destructive merge contract and the per-language leaf scoping (P1-P5) are enforced in one place. A live instance is provisioned by invoking the odoo-instance skill (never the raw odoo-instance-ops agent).

Out of Scope

• A single user-facing label or string= added while writing code -> use odoo-coding (it applies the terminology-consistency lookup inline; this skill is for module-scale translation)
• Checking whether a RENDERED screen shows the right language / locale at runtime -> use odoo-ui-review (live browser), not this static export-and-merge pipeline
• Designing a new model or feature before any code -> use odoo-solution-design
• Reviewing translation code or a .po diff for bugs -> use odoo-code-review
• Writing the production code whose strings will later be translated -> use odoo-coding

Standalone-first fallback

i18n REQUIRES a running Odoo instance with the target module installed. Export (--i18n-export) walks the live registry to enumerate translatable terms, and validation reloads the module against a real DB - both need an instance. There is NO no-DB workaround: babel or a raw PO parser alone cannot discover a module's translatable terms the way Odoo's registry does, so every "translate without an instance" path produces an INCOMPLETE or WRONG result and must be refused.

When no instance is available, BLOCK with status NEEDS_CONTEXT (Continuation Contract blocked_reason); do not improvise a partial export. Acquire an instance by invoking the odoo-instance skill (never the raw odoo-instance-ops agent) per docs/reference/INSTANCE-LIFECYCLE.md (allocator/lifecycle decision tree) and resume at P2. Ground the exact odoo-bin export/reload flags for the target series before invoking - the CLI surface differs per version (server flags v8-v18 vs the i18n subcommand v19+):

cli_help(command='i18n-export', odoo_version='<target>')   # v8-v18 (server flag)
cli_help(command='i18n', odoo_version='19.0')              # v19+ (subcommand)

When OSM itself is unreachable, flag-grounding falls back to the instance's own odoo-bin --help; the instance requirement is absolute and never degrades to a no-DB path.

The 6-phase pipeline

Run phases in order. Each phase names its model tier; dispatch follows ${CLAUDE_PLUGIN_ROOT}/skills/_shared/concurrency-guard.md (Mode B) for any fan-out. Artifacts land under the Tier-2 ISOLATE dir; resolve it via the resolve-capture-substitute protocol in ${CLAUDE_PLUGIN_ROOT}/snippets/state-root-resolution.md (captured path shown as <ISOLATE_DIR> below) - <ISOLATE_DIR>/i18n/<slug>-<date>/. The full non-destructive recipe (every command, the diff-review reconcile, the validation gates, the glossary) lives in references/i18n-recipe.md.

P0 - Scope gate [sonnet, STOP]. Resolve the target language list by precedence (highest first), then echo which source was used:

1. Explicit languages in the request/args.
2. Machine-global registry: read ${ODOO_AI_HOME:-$HOME/.odoo-ai}/i18n.json and use its default_languages array if present and non-empty.
3. Infer from existing <lang>.po filenames in each module's i18n/ directory (<module>/i18n/<lang>.po); skip this tier when no i18n/ dir exists.
4. Query the confirmed instance: res.lang records with active = True (codes).
5. Default ["vi_VN"].

en_US is mandatory, independent of the tiers above. After resolving the target languages, set activation_languages = {"en_US"} union target_languages. en_US (Odoo's base/source language) is ALWAYS loaded into the DB alongside every target language (recipe KT3) - none of the tiers above can produce it (Odoo ships no en_US.po), so it MUST be added here. This governs the DB-activation set passed to every --load-language/loadlang call ONLY; it does NOT add en_US as a translation deliverable (no en_US.po is exported or merged).

Echo the resolved language list (target languages + the activation_languages set) AND the source tier that produced it in the scope summary, then STOP for approval before any export or DB op.

Also in P0: confirm an instance is available (else BLOCK per ## Standalone-first fallback). Resolve each module name to its directory and dependency closure. Emit a one-line scope summary (modules x target_languages x series + dependency order + language-source tier) and STOP for approval in a single turn before any export or DB op.

P1 - Glossary build [haiku or sonnet]. Assemble the translation memory the later phases reuse: read the already-translated <lang>.po of core Odoo and the module's dependency modules, load the project glossary.yml (domain/regulatory terms + their source citation) - Tier-2 SHARE, resolved via the same state-root-resolution.md protocol (captured path shown as <SHARE_DIR> below): <SHARE_DIR>/glossary.yml - and for any field-mapped term confirm the canonical label via OSM (see the glossary layer in the recipe). Build the TM per language (one independent memory per language, covering all in-scope modules). Write each assembled TM to <ISOLATE_DIR>/i18n/<slug>-<date>/glossary-tm-<lang>.json (one file per target language). Do NOT share or merge TM across languages. Sonnet when the scope spans domain/regulatory terminology; haiku for a plain module.

P2 - Export .pot template [sonnet]. Per L1 of the recipe: install the module, then export a .pot TEMPLATE on a clean per-module install in an isolated DB, in dependency order (a .pot template needs NO language load - the L1 load step applies only to a translated .po re-export). Never export over a maintained .po. ALWAYS re-export the .pot FRESH from the currently-installed code on every invocation - never reuse a committed or prior-run .pot already on disk (a stale template misses the run's new/renamed terms and silently under-merges; recipe gate 5). The .pot is language-agnostic (shared across all target languages - one FRESH export per module per run, not per language). The per-version flags and their rationale - --load-language (activate in DB) vs --language/-l (select export file), --skip-auto-install v17-v18, one fresh DB per module v8-v16, the odoo-bin i18n subcommand v19+ - live in the recipe; ground the exact form via cli_help above (command='i18n-export' v8-v18, command='i18n' v19+).

P3 - Translate [dispatch odoo-translator]. Dispatch the odoo-translator agent as a subagent launch for EACH (module-cluster × language) pair - the Cartesian product of module clusters and target languages. Each leaf carries exactly ONE language; never bundle multiple languages in a single leaf. Each leaf runs the L2 re-export + diff-review reconcile and L3 hand-translation of the residual for its specific language. Loop order: see ## Multi-language loop order in references/i18n-recipe.md (.pot exported once per module, .po/glossary/validate per-lang). See the dispatch contract below for the model and brief.

P4 - Validate [haiku]. Run all validation gates (recipe § Validation) for EACH target language independently. P4 is the orchestrator-level gate run after all P3 leaves finish - a second, independent pass over each leaf's own Round 4 self-check, not a replacement for it. Per language: run the git-ops diff-review adjudication on <lang>.po (BLOCK on any un-adjudicated or WRONG-ruled loss - that means an overwrite slipped through without the load step), the per-entry placeholder-integrity check, and the Odoo -u <module> reload (NOT msgfmt). Pre-condition for each language's reload: the target language must be LOADED in the DB first (--load-language=<lang> v8-v18 / i18n loadlang -l <lang> v19+); an absent language makes the reload pass silently while translations stay inactive

• a false pass. en_US (the base language) MUST be active too (KT3) - confirm BOTH en_US and each <lang>, never the target language alone. Also verify the .pot consumed was re-exported THIS run (recipe gate 5), not a stale on-disk template. A clean reload with no translation error in the log is the pass signal per language. See docs/reference/INSTANCE-LIFECYCLE.md for the reload semantics. Each per-language -u <module> reload must run against the SAME lease as the P2/L1 -i install that created the DB via Odoo create-on-init, or --mode exclusive on a declared DB with the module pre-installed - never a fresh ephemeral lease (reserve-only = uncreated DB, -u will fail).

P5 - Consistency audit + report [sonnet default; opus ONLY when the in-scope terminology is domain/legal/regulatory (e.g. accounting circulars) - never for module or language count alone; ADVISORY]. Audit terminology consistency across the translated modules for EACH target language separately. This phase is ADVISORY and NEVER blocking: it surfaces inconsistencies for a human to decide on, but it does NOT auto-edit or auto-dedup. Critically, legally independent regimes (e.g. the Vietnam accounting circulars TT200 / TT133 / TT99) MUST NOT be deduped even when their msgids match - each regime's translation stays complete and self-standing, and an incidental string match is never a reason to share or rewrite a translation across regimes. Write findings per language to <ISOLATE_DIR>/i18n/<slug>-<date>/consistency-audit-<lang>.md (one file per target language).

Dispatch contract -> odoo-translator

When composing the dispatch prompt for any specialist agent you dispatch, fill the caller-side skeleton in ${CLAUDE_PLUGIN_ROOT}/snippets/dispatch-brief.md (read it by path) plus the target agent's family delta; never inline that file verbatim into a hard-leaf brief.

P3 dispatches the odoo-translator agent as a subagent launch - one leaf per (module-cluster × language) pair. Each leaf is scoped to exactly ONE language. Carry a brief with: the target module(s), the single target language, series; the glossary TM path for that language (glossary-tm-<lang>.json) from P1; the maintained <lang>.po and fresh <module>.pot paths; and the validation gates the leaf must self-check. Pass the model both as a DISPATCH MODEL: line in the brief and as the Agent model parameter:

• sonnet (default) for a plain module translation.
• opus when the scope carries domain / legal / regulatory terminology (e.g. accounting circulars, statutory report labels) where a wrong term has compliance cost.

The leaf carries the worker brief (${CLAUDE_PLUGIN_ROOT}/snippets/worker-brief.md) and appends its decisions to the worklog (${CLAUDE_PLUGIN_ROOT}/snippets/worklog-contract.md). It does the re-export + translation directly - there is no OSM i18n tool, so it uses shell odoo-bin (the git-ops diff-review + commit stay with the skill, never the leaf), and uses OSM only to confirm canonical field labels, e.g.:

entity_lookup(kind='field', model='account.move', field='amount_total', odoo_version='<target>')

.po/.pot file format constraint (authoring and hand-editing): Every message entry in a .po or .pot file MUST carry a #. module: <technical_name> extractor comment on the line immediately before the #: <file>:<line> location reference. A hand-written or hand-patched entry missing this comment causes translate.py to crash at module load and Runbot misattributes the failure to a later module. Odoo's --i18n-export generates this comment automatically; the re-export preserves it, and it must be added manually when entries are written by hand.

Artifacts

All under <ISOLATE_DIR>/i18n/<slug>-<date>/:

• glossary-tm-<lang>.json - assembled translation memory per target language (P1; one file per language; TM of one language is never shared with another)
• <module>.pot - exported template(s) (P2; language-agnostic, shared across all target languages)
• translation-report-<lang>.json - per-module diff-review adjudication log (removed/changed/added msgids + correct/wrong rulings) for each language (an un-adjudicated or WRONG-ruled loss is a BLOCK)
• consistency-audit-<lang>.md - the advisory P5 findings per language

Continuation Contract

When the run finishes (or pauses at the P0 gate or an instance BLOCK), append a Continuation Contract block per ${CLAUDE_PLUGIN_ROOT}/snippets/continuation-contract.md (status / produced / next). produced lists the artifacts above; a missing instance is status: NEEDS_CONTEXT with the instance requirement as blocked_reason. Additive output for the run-harness - it does not change anything produced above.