Internationalization

Scope

Internationalization has four surfaces:

• CLI display language;
• experience card content language;
• retrieval matching across languages;
• public documentation language.

Runtime Language Policy

Language is not persisted in config.json.

• CLI human output is English only for predictable open-source behavior.
• JSON output field names remain stable English.
• The fixed prompt-time recall frame is English. User-authored card content keeps the language chosen for that card, and agent-facing instructions keep disclosure semantics explicit without adding response-language rules.
• Experience card content and user-visible recall output currently support only English and Chinese, because current mainstream LLMs handle these two languages most reliably for coding-agent workflows.

Policy Layers

OME separates language responsibility by surface:

Layer	Policy	Why
Framework	English	Stable agent instructions, CLI behavior, JSON contracts, tests, and docs routing.
Evidence	Original language	User corrections, acceptance wording, and counterexamples need audit fidelity.
Card content	English or Chinese	Cards should match the language the user is likely to use in future recall prompts.
Agent output	Agent default response language	The final reminder/disclosure is user-facing prose, not a machine contract.

This split avoids runtime translation. For example, if a Chinese-speaking user corrects an agent in Chinese and will likely ask future tasks in Chinese, the approved card should usually stay Chinese. That preserves the original trigger phrases, avoids translation drift, and improves future lexical recall.

CLI

CLI help and human result output are English. Do not add a runtime language toggle for the CLI human surface.

Experience Card Language

Each card should declare a content language. Card fields such as title, summary, criteria, triggers, topics, and rule follow the language chosen when the card is created or approved. That language must be English or Chinese. Commands, package names, file paths, APIs, and technical terms stay unchanged.

auto and mixed may still appear in older cards or internal detection output, but newly approved cards should settle on en or zh content.

The hook frame injected into agents is always English: labels and instructions are framework text. Card content can still appear in the card's own language. The agent's user-visible reminder and final used-card disclosure rely on the agent's normal response-language behavior. Do not rely on hook-time translation; the hook hot path stays local and does not call an LLM.

Retrieval Language

The retrieval engine must support cross-language matching signals, but it must not translate in the hook hot path.

Recommended approach:

• choose English or Chinese during reflect candidate creation based on user preference, dominant source wording, and future recall usefulness;
• preserve original-language user wording in evidence and source archives;
• allow aliases per card;
• preserve command, package, path, and code tokens;
• use Chinese phrase/bigram matching;
• evaluate bilingual fixtures in ome eval recall.

Documentation Language

Public-facing docs use path-based locales:

• English: /
• Simplified Chinese: /zh/

Each locale keeps the same directory shape:

docs/guides/quickstart.md
docs/zh/guides/quickstart.md

Future languages should add a new top-level locale directory and a matching locales entry in docs/.vitepress/config.ts. Do not create language suffix routes such as quickstart.zh-CN.md.

Commands, paths, config keys, frontmatter keys, API fields, and package names must not be translated. Translate the explanation around them instead.

Source archives and user-voice records may stay in their original language, but public entry points should link to the matching language version.