Multilingual Sites

A Context site can show every page in several languages at the same address. You declare the reader languages; the Agent translates approved articles and navigation titles during delivery; the site shows each reader their language and falls back to the original where a translation is missing. Approved knowledge in the primary language stays the only source of truth: translations are a reader projection and never change Review, verification or the knowledge package.

mermaid

flowchart LR
  approved["Approved article<br/>primary language"] --> tr["Translation step"]
  tr --> files["translations/zh-CN/..."]
  approved --> build["context build"]
  files --> build
  build --> page["One page,<br/>every language"]

Declaring languages

site: {
  lang: "en-US",
  locales: { "zh-CN": { title: "项目知识" } },
}

Each locale may override label, title, description and home. Set only the homepage fields that differ: an unset home title, slogan, description, hero actions or resources falls back to the site's own home setting, and then to the built-in default, so a translated title alone keeps the primary language's actions and resource cards. Links, navigation and custom pages need no per-language routes, because every page carries all languages. A reader's saved choice wins, then the browser's languages, then site.lang; the choice is remembered under site.localePreferenceKey (default context-locale:<package>:<base>), which several sites on one origin can share. Without site.locales the language button still switches the interface between Chinese and English.

Where translations live

Path	Content
`translations/<tag>/<approved-path>.md`	Translated article; frontmatter holds `title`, optional `description` and a `translation` record with locale, article identity, source digest and time
`translations/<tag>/knowledge-map.yaml`	Translated navigation titles keyed by knowledge-map entry

Translations are formal content of the Context knowledge workspace: they are committed, included in versions and package fingerprints, and changing one rebuilds the website.

Freshness

Each translation records the digest of the approved title, description and body it was made from:

State	Meaning	On the site
`current`	Digest matches	Translation shown
`stale`	Approved article changed since	Translation shown with an outdated notice and a button to switch to the original
`missing`	No translation file	Original shown with a notice

Runtime metadata changes do not make a translation stale. Translations whose article no longer exists are reported as orphans and removed on the next submission. context-site-map.json lists translated, stale and missing counts per locale.

The translation step

When a package declares locales and anything is not current, the workflow adds a translation step after package template approval and before the knowledge workspace version is recorded. The Agent runs it:

bash

context translate status --format json
context translate prepare --format json
context translate submit --input <file> --format json
context translate skip --digest <expected_digest> --format json

prepare lists pending articles and navigation titles with an expected_digest; submit takes the translated files and titles:

yaml

expected_digest: <from prepare>
articles:
  - locale: zh-CN
    approved_path: knowledge/sop/example.md
    file: .tmp/agent-payloads/translations/zh-CN/sop/example.md
map_entries:
  - locale: zh-CN
    key: getting-started
    title: 入门

A translation must keep every section marker, id and order, every fenced code block (Mermaid labels may change) and every link target. The submission is validated as a whole and saves nothing if any item fails; a digest from before an approved change is rejected. skip publishes the current pending items in the primary language for this iteration only — the next approved change asks again.

What readers see

Each page is published once with every language and the reader's language selects what is visible. Navigation titles without a translation use the translated article title, then the original. Search covers every language, and opening a result in another language switches to it. LLM Docs and the Changelog stay in the primary language. For other site options, see Documentation Sites.

多语言站点

Context 站点可以在同一地址下用多种语言显示每个页面。你声明读者语言；Agent 在交付阶段翻译已批准的文章和导航标题；站点为每位读者显示其语言，缺少翻译时则回退到原文。主语言中已批准的知识始终是唯一的真源：翻译只是面向读者的投影，绝不会改变审核、验证或知识包。

mermaid

flowchart LR
  approved["已批准的文章<br/>主语言"] --> tr["翻译步骤"]
  tr --> files["translations/zh-CN/..."]
  approved --> build["context build"]
  files --> build
  build --> page["一个页面，<br/>所有语言"]

声明语言

site: {
  lang: "en-US",
  locales: { "zh-CN": { title: "项目知识" } },
}

每个 locale 都可以覆盖 label、title、description 和 home。只需设置不同的首页字段：未设置的 home 标题、标语、描述、首屏操作或资源卡片会先沿用站点自身的 home 设置，再回退到内置默认值，因此只翻译标题时，仍会保留主语言的操作按钮和资源卡片。链接、导航和自定义页面都不需要按语言区分路由，因为每个页面都包含所有语言。读者保存的选择优先，其次是浏览器语言，最后是 site.lang；该选择保存在 site.localePreferenceKey 下（默认为 context-locale:<package>:<base>），同一源站下的多个站点可以共享它。即使没有 site.locales，语言按钮仍可在中文和英文之间切换界面。

翻译存放在哪里

路径	内容
`translations/<tag>/<approved-path>.md`	翻译后的文章；frontmatter 包含 `title`、可选的 `description`，以及一条 `translation` 记录，其中有 locale、文章身份标识、来源摘要和时间
`translations/<tag>/knowledge-map.yaml`	按知识地图条目索引的翻译后导航标题

翻译是 Context 知识工作区的正式内容：它们会被提交，纳入版本和知识包指纹，修改任何一项翻译都会重新构建网站。

时效性

每份翻译都会记录它所依据的已批准标题、描述和正文的摘要：

状态	含义	站点上的表现
`current`	摘要一致	显示翻译
`stale`	已批准的文章此后发生了变化	显示翻译，并附带过期提示和一个切换到原文的按钮
`missing`	没有翻译文件	显示原文并附带提示

运行时元数据的变化不会让翻译过期。如果翻译对应的文章已不存在，它会被报告为孤立翻译，并在下次提交时移除。context-site-map.json 会列出每个 locale 已翻译、已过期和缺失的数量。

翻译步骤

当知识包声明了 locale 且存在不是最新的内容时，工作流会在知识包模板批准之后、记录知识工作区版本之前加入一个翻译步骤。由 Agent 执行：

bash

context translate status --format json
context translate prepare --format json
context translate submit --input <file> --format json
context translate skip --digest <expected_digest> --format json

prepare 会列出待翻译的文章和导航标题，并给出 expected_digest；submit 接收翻译后的文件和标题：

yaml

expected_digest: <from prepare>
articles:
  - locale: zh-CN
    approved_path: knowledge/sop/example.md
    file: .tmp/agent-payloads/translations/zh-CN/sop/example.md
map_entries:
  - locale: zh-CN
    key: getting-started
    title: 入门

翻译必须保留每个章节标记、id 及其顺序，每个围栏代码块（Mermaid 标签可以修改）以及每个链接目标。提交会作为一个整体进行校验，只要有任何一项失败就不会保存任何内容；在某次已批准的变更之前得到的摘要会被拒绝。skip 只在本轮迭代中以主语言发布当前待处理的条目——下一次已批准的变更会再次要求翻译。

读者看到什么

每个页面只发布一次，包含所有语言，由读者的语言决定显示哪一种。没有翻译的导航标题会使用翻译后的文章标题，再没有则使用原文。搜索覆盖所有语言，打开另一种语言的搜索结果时会切换到该语言。LLM Docs 和 Changelog 保持主语言。关于其他站点选项，请参阅文档站。

Multilingual Sites ​

Declaring languages ​

Where translations live ​

Freshness ​

The translation step ​

What readers see ​

多语言站点 ​

声明语言 ​

翻译存放在哪里 ​

时效性 ​

翻译步骤 ​

读者看到什么 ​