docs(i18n): document complete Docsy locale support

content/docs/about/_index.md

@@ -32,7 +32,7 @@ run on it today, this one among them.
 
 ## What the theme provides {#what-oink-provides}
 - The documentation and blog shell: navigation, sidebar tree, table of contents, breadcrumbs, pager, dark mode, print view and accessible interaction.
-- The multilingual frame: translation routing, fallback for untranslated pages, language weighting, RTL, and 32 interface language packs.
+- The multilingual frame: translation routing, fallback for untranslated pages, language weighting, RTL, and 32 complete interface catalogs.
 - Local runtimes: Mermaid, KaTeX, Markmap, Swagger UI, Redoc, Asciinema, ECharts, Infographic and local full-text search.
 - Content components: callouts, tabs, steps, cards, field lists, file trees, galleries, badges, keys and more — most with a native Markdown form.
 - Content types: beyond ordinary documentation, built-in book numbering and cross-references, release and download pages, data-driven landing pages, and OpenAPI reference pages.
@@ -63,7 +63,7 @@ check each project's current documentation before choosing.
 | Does a consuming site need npm | No | Yes: Bootstrap and Font Awesome are mounted from `node_modules/` | No | Yes |
 | Where front-end assets come from | All committed to the theme repository; `VENDOR.json` records version, source, licence and checksum | jQuery is loaded from a CDN on every page unconditionally; Mermaid, KaTeX and others also fetch from a CDN at build time | Prebuilt artifacts committed to the repository | npm dependencies |
 | How components are written | Native Markdown attributes and fences first, 29 shortcodes as the fallback | Shortcodes (19) | Shortcodes (29) first; callouts also have a `> [!NOTE]` native form | MDX (React components) |
-| Multilingual | Hugo multilingual + 32 interface language packs | Hugo multilingual (OINK's packs are inherited from it) | Hugo multilingual + 21 interface language packs | Built-in i18n framework |
+| Multilingual | Hugo multilingual + 32 complete interface catalogs | Hugo multilingual + 31 interface locale files | Hugo multilingual + 21 interface language packs | Built-in i18n framework |
 | Book numbering and cross-references / release and download pages / data-driven landing pages | Built into the theme | None | None | Build your own or find a plugin |
 
 Two qualifications. Per-page Markdown output and `llms.txt` are not unique to

content/docs/about/_index.zh.md

@@ -22,7 +22,7 @@ OINK 是一款独立的 [Hugo](https://gohugo.io/) 主题，用于搭建中大
 
 ## 主题的职责 {#what-oink-provides}
 - 文档与博客外壳：导航、侧栏树、目录、面包屑、翻页、深色模式、打印视图与无障碍交互。
-- 多语言框架：译文路由、缺译回退、语言权重、RTL，以及 32 个界面语言包。
+- 多语言框架：译文路由、缺译回退、语言权重、RTL，以及 32 份完整界面语言包。
 - 本地运行时：Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic 与本地全文检索。
 - 内容组件：提示块、标签页、步骤、卡片、参数表、文件树、画廊、徽章、按键等，多数有 Markdown 原生形态。
 - 内容类型：普通文档之外，还内置书籍编号与交叉引用、发布与下载页、数据驱动的 Landing 首页、OpenAPI 文档页。
@@ -48,7 +48,7 @@ OINK 是一款独立的 [Hugo](https://gohugo.io/) 主题，用于搭建中大
 | 消费站点要不要 npm | 不要 | 要：Bootstrap 与 Font Awesome 从 `node_modules/` 挂载 | 不要 | 要 |
 | 前端资源从哪来 | 全部提交在主题仓库，`VENDOR.json` 记录版本、来源、许可与校验值 | 每页无条件加载 CDN 上的 jQuery；Mermaid、KaTeX 等还会在构建期请求 CDN | 预编译产物提交在仓库 | npm 依赖 |
 | 组件写法 | Markdown 原生属性与围栏为主，29 个 shortcode 兜底 | shortcode（19 个） | shortcode（29 个）为主，提示块有 `> [!NOTE]` 原生形态 | MDX（React 组件） |
-| 多语言 | Hugo 多语言 + 32 个界面语言包 | Hugo 多语言（OINK 的语言包由此继承） | Hugo 多语言 + 21 个界面语言包 | 内置 i18n 框架 |
+| 多语言 | Hugo 多语言 + 32 份完整界面语言包 | Hugo 多语言 + 31 个界面 locale 文件 | Hugo 多语言 + 21 个界面语言包 | 内置 i18n 框架 |
 | 书籍编号与交叉引用 / 发布下载页 / 数据驱动落地页 | 主题内置 | 无 | 无 | 需自建或找插件 |
 
 两点补充。每页 Markdown 输出与 `llms.txt` 不是 OINK 独有的能力，Docsy 与 Hextra 也有，三者都要站点在 `outputs` 里显式打开。表格最后一行的三项只有 OINK 内置，它们来自 PGSTY 自己的生产站点，不是通用文档站的必需品。主题的交互功能默认关闭，搜索、缩放、评论与反馈都要站点显式打开。

content/docs/about/features.md

@@ -83,10 +83,10 @@ for it.
 Multilingual support uses Hugo's own mechanism: translation routing, a language
 picker ordered by weight, fallback for untranslated pages, RTL, and canonical
 and alternate metadata. Interface strings come in 32 language packs sharing one
-key schema. English, Simplified Chinese (`zh-cn` and the generic `zh`) and
-Traditional Chinese (`zh-tw`) are human-reviewed; the other locales keep the
-translations inherited from Docsy, with English fallbacks for the keys OINK
-added.
+192-key schema: all 31 locale filenames supported by Docsy, plus generic `zh`.
+Every pack now contains native OINK interface text rather than English
+placeholder blocks; `zh` and `zh-cn` use Simplified Chinese and `zh-tw` uses
+Traditional Chinese.
 
 → [Languages](/docs/customize/i18n/)
 

content/docs/about/features.zh.md

@@ -46,7 +46,11 @@ aliases:
 
 ## 双语与 32 个界面语言 {#multilingual}
 
-多语言走 Hugo 原生机制：译文路由、按权重排序的语言选择器、缺译回退、RTL、以及 canonical 与 alternate 元数据。界面文案有 32 个语言包，共用同一套 key；英语、简体中文（`zh-cn` 与通用 `zh`）与繁体中文（`zh-tw`）经过人工审校，其余语言保留 Docsy 继承下来的翻译，OINK 新增的键先用英文兜底。
+多语言走 Hugo 原生机制：译文路由、按权重排序的语言选择器、缺译回退、RTL，
+以及 canonical 与 alternate 元数据。界面文案有 32 份语言包，共用 192 键
+schema：Docsy 支持的 31 个 locale 文件名，再加通用 `zh`。每份语言包都使用目标
+语言覆盖完整 OINK 界面，不再保留英文占位块；`zh` 与 `zh-cn` 使用简体中文，
+`zh-tw` 使用繁体中文。
 
 → [多语言](/zh/docs/customize/i18n/)
 

content/docs/customize/config.md

@@ -459,7 +459,7 @@ reads the translation relationships it establishes:
 | `languages.<lang>.locale` | string | | The full locale, used for `<html lang>` and SEO |
 | `languages.<lang>.weight` | integer | | Language order, and the cycle order when clicking the language icon |
 | `languages.<lang>.title` | string | | The site name in that language |
-| `languages.<lang>.languageDirection` | string | ltr | Set `rtl` for a right-to-left language |
+| `languages.<lang>.direction` | string | ltr | Set `rtl` for a right-to-left language |
 {.fields meta="type default"}
 
 Paired files, anchor alignment and fallback for untranslated pages are in

content/docs/customize/config.zh.md

@@ -412,7 +412,7 @@ outputs:
 | `languages.<lang>.locale` | string | | 完整 locale，用于 `<html lang>` 与 SEO |
 | `languages.<lang>.weight` | integer | | 语言顺序，也是点击语言图标时的循环顺序 |
 | `languages.<lang>.title` | string | | 该语言的站名 |
-| `languages.<lang>.languageDirection` | string | ltr | RTL 语言设为 `rtl` |
+| `languages.<lang>.direction` | string | ltr | RTL 语言设为 `rtl` |
 {.fields meta="type default"}
 
 写作侧的对等文件、锚点对齐与缺译回退见[多语言](/zh/docs/customize/i18n/)。

content/docs/customize/i18n.md

@@ -119,17 +119,23 @@ fully is in [Navigation and menus](/docs/customize/navigation/).
 `en.yaml`; a single-language site needs only one `data/home.yaml`. See
 [Home and landing pages](/docs/customize/home/).
 
-**Interface strings**: the theme ships interface strings for 32 locales.
-English, Simplified Chinese (`zh` and `zh-cn`) and Traditional Chinese
-(`zh-tw`) are reviewed; the rest keep the translations inherited from Docsy,
-with English fallbacks for the labels OINK added. To change one, create a file
-of the same name under the site's own `i18n/` and write only the keys you
-override:
+**Interface strings**: the theme ships 32 complete interface catalogs: the 31
+locale filenames supported by Docsy, plus generic `zh`. Every catalog contains
+all 192 OINK keys in its native language; none relies on generated English
+fallback blocks. `zh` and `zh-cn` use Simplified Chinese, while `zh-tw` uses
+Traditional Chinese. The exact locale and placeholder contract is recorded in
+[Architecture](/docs/design/architecture/#interface-localization). To change a
+string, create a file of the same name under the site's own `i18n/` and write
+only the keys you override:
 
 ```yaml {title="i18n/en.yaml"}
 ui_search: Search the docs
 ```
 
+Keep the concrete `locale: zh-CN` shown for the non-default language when
+supporting Hugo 0.160.x with regional Chinese catalogs present. Bare
+`locale: zh` is safe in the same configuration from Hugo 0.161 onward.
+
 ## Untranslated fallback and the language picker {#fallback}
 
 The language picker's icon is itself a link: clicking it moves to the next
@@ -194,7 +200,7 @@ languages:
   ar:
     label: العربية
     locale: ar
-    languageDirection: rtl
+    direction: rtl
     weight: 3
 ```
 

content/docs/customize/i18n.zh.md

@@ -98,12 +98,20 @@ languages:
 
 **首页数据** 按语言取文件：`data/home/en.yaml`、`data/home/zh.yaml`。当前语言没有对应文件时回退到 `en.yaml`；单语言站点用一个 `data/home.yaml` 即可。见[首页与落地页](/zh/docs/customize/home/)。
 
-**界面文案**：主题自带 32 个 locale 的界面字符串。英文、简体中文（`zh` 与 `zh-cn`）和繁体中文（`zh-tw`）经过审校，其余语言保留继承自 Docsy 的翻译，OINK 新增的标签用英文兜底。要改某一条，在站点自己的 `i18n/` 下建同名文件，只写要覆盖的键：
+**界面文案**：主题自带 32 份完整界面语言包，即 Docsy 支持的 31 个 locale
+文件名，再加通用 `zh`。每份语言包都以目标语言覆盖 OINK 的全部 192 个键，
+不再依赖生成的英文 fallback。`zh` 与 `zh-cn` 使用简体中文，`zh-tw` 使用繁体
+中文；完整 locale 与占位符契约见[架构](/zh/docs/design/architecture/#interface-localization)。
+要改某一条，在站点自己的 `i18n/` 下建同名文件，只写要覆盖的键：
 
 ```yaml {title="i18n/zh.yaml"}
 ui_search: 搜索文档
 ```
 
+如果需要兼容 Hugo 0.160.x，并且地区化中文语言包同时存在，请为非默认的通用 `zh`
+语言保留具体的 `locale: zh-CN`。从 Hugo 0.161 起，相同配置也可以使用裸
+`locale: zh`。
+
 ## 缺译回退与语言选择器 {#fallback}
 
 语言选择器的图标本身是一个链接：点击它按 `weight` 顺序切到下一种语言（在末尾回到第一种），悬停或键盘聚焦才展开列出全部语言的菜单，触摸屏上菜单不展开，点按即切换。双语站点因此一次点击即可来回切换。
@@ -152,7 +160,7 @@ languages:
   ar:
     label: العربية
     locale: ar
-    languageDirection: rtl
+    direction: rtl
     weight: 3
 ```
 

content/docs/design/_index.md

@@ -46,7 +46,7 @@ proposal.
 
 | Contract                                      | Authority                                                                                            |
 | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| [Architecture](/docs/design/architecture/)    | Build, configuration, diagnostics, featured images, output, security, accessibility, and performance |
+| [Architecture](/docs/design/architecture/)    | Build, configuration, diagnostics, localization, featured images, output, security, accessibility, and performance |
 | [Components](/docs/design/components/)        | Component API, Book and release primitives, validation, and output degradation                       |
 | [Shell and navigation](/docs/design/shell/)   | Navigation, search, blog presentation, actions, taxonomies, and page-end composition                 |
 | [Landing pages](/docs/design/landing/)        | Landing data, the 22-section registry, runtime, accessibility, and outputs                           |

content/docs/design/_index.zh.md

@@ -34,7 +34,7 @@ cascade:
 
 | 契约                                      | 权威范围                                             |
 | ----------------------------------------- | ---------------------------------------------------- |
-| [架构契约](/zh/docs/design/architecture/) | 构建、配置、诊断、特色图片、输出、安全、无障碍与性能 |
+| [架构契约](/zh/docs/design/architecture/) | 构建、配置、诊断、本地化、特色图片、输出、安全、无障碍与性能 |
 | [组件契约](/zh/docs/design/components/)   | 组件 API、Book 与发布原语、校验和输出降级            |
 | [外壳与导航契约](/zh/docs/design/shell/)  | 导航、搜索、博客展示、操作、分类法与页尾组合         |
 | [落地页契约](/zh/docs/design/landing/)    | 落地页数据、22 种区块注册表、运行时、无障碍与输出    |

content/docs/design/architecture.md

@@ -1,10 +1,10 @@
 ---
 title: Architecture contract
 linkTitle: Architecture
-description: Repository assembly, configuration, diagnostics, output, performance, security, CSS, accessibility, and release-state boundaries.
+description: Repository assembly, configuration, diagnostics, localization, output, performance, security, CSS, accessibility, and release-state boundaries.
 weight: 10
 icon: fa-solid fa-sitemap
-search_keywords: [OINK architecture, repository boundary, runtime, output formats, security, accessibility, performance]
+search_keywords: [OINK architecture, repository boundary, runtime, i18n, Docsy locales, output formats, security, accessibility, performance]
 contract_status: released-v1.0.0
 ---
 
@@ -74,6 +74,49 @@ requires `appId`, `apiKey`, and `indexName`; incomplete configuration warns and
 emits no request. Draw.io loads only when rendered content contains PNG or SVG
 candidates, then inspects each distinct image URL once.
 
+## Interface localization {#interface-localization}
+
+> [!NOTE] Implemented, not yet released
+> This locale expansion describes the feature branch. It is not a published
+> module capability until a later release tag resolves through the Go proxy.
+
+OINK ships native interface catalogs for the 31 locale filenames present in
+[`google/docsy@64f51c5`](https://github.com/google/docsy/tree/64f51c5bde2abd2e8a001cb31b32656f5800ca56/theme/i18n),
+plus generic `zh` as the Simplified Chinese default:
+
+```text
+ar az bg bn de en es et fa fi fr he hi hu it ja ko nl no oc pl pt-br ro ru
+sr-cyrl sr-latn sv tr uk zh-cn zh-tw
+```
+
+That is a compatibility scope, not a runtime dependency on Docsy and not a
+claim that a consumer's authored content has been translated. A new Docsy
+locale does not enter OINK automatically: it needs a complete OINK catalog and
+the same review as every existing locale.
+
+`i18n/en.yaml` owns the 192-key schema. Every one of the 32 OINK bundles has
+exactly that key set and native UI text; an English value may remain only when
+it is a reviewed product name, punctuation token, conventional abbreviation,
+or genuine word shared by the target language. There are no generated English
+fallback blocks. `zh` and `zh-cn` carry Simplified Chinese, while `zh-tw`
+carries Traditional Chinese.
+
+On the Hugo 0.160.x compatibility floor, a non-default generic `zh` language
+key must set the concrete `locale: zh-CN` value when the regional Chinese
+catalogs are also present. Bare `locale: zh` resolves in that configuration
+from Hugo 0.161 onward. This affects language configuration, not the
+`i18n/zh.yaml` catalog name.
+
+Runtime placeholders such as `%s`, `{count}`, and `{{ .Count }}` may move to a
+grammatically natural position but must remain byte-for-byte identical. Values
+are scalars. Catalogs contain no hidden bidirectional controls; Arabic,
+Persian, and Hebrew direction still comes from the consumer language setting
+(`direction: rtl`), not from characters injected into translations.
+`bin/check-i18n.py` enforces the locale set, schema, value shape, placeholders,
+directional controls, and the small reviewed set of English-identical terms.
+Adding a visible string therefore means translating it in every bundle in the
+same change, not running a fallback generator.
+
 ## Featured images {#featured-images}
 
 Hugo's `images` is the single authored API; `params.images` is only the

content/docs/design/architecture.zh.md

@@ -1,10 +1,10 @@
 ---
 title: 架构契约
 linkTitle: 架构
-description: 仓库装配、配置、诊断、输出、性能、安全、CSS、无障碍与发布状态的边界。
+description: 仓库装配、配置、诊断、本地化、输出、性能、安全、CSS、无障碍与发布状态的边界。
 weight: 10
 icon: fa-solid fa-sitemap
-search_keywords: [OINK 架构, 仓库边界, 运行时, 输出格式, 安全, 无障碍, 性能]
+search_keywords: [OINK 架构, 仓库边界, 运行时, i18n, Docsy 语言, 输出格式, 安全, 无障碍, 性能]
 contract_status: released-v1.0.0
 ---
 
@@ -63,6 +63,43 @@ OINK 没有通用的键名重命名注册表。仍需给出迁移诊断的过渡
 Draw.io 只在渲染内容含 PNG 或 SVG 候选图片时加载，并且每个不同的图片 URL
 只检查一次。
 
+## 界面本地化 {#interface-localization}
+
+> [!NOTE] 已实现，尚未发布
+> 此处语言扩展描述的是特性分支。在后续版本标签可以通过 Go Proxy 解析之前，
+> 它还不是已发布模块的能力。
+
+OINK 为
+[`google/docsy@64f51c5`](https://github.com/google/docsy/tree/64f51c5bde2abd2e8a001cb31b32656f5800ca56/theme/i18n)
+中现有的 31 个 locale 文件名提供原生界面文本，并额外保留通用 `zh` 作为简体中文
+默认值：
+
+```text
+ar az bg bn de en es et fa fi fr he hi hu it ja ko nl no oc pl pt-br ro ru
+sr-cyrl sr-latn sv tr uk zh-cn zh-tw
+```
+
+这是一项兼容范围，不代表运行时依赖 Docsy，也不声称消费站点编写的正文已经翻译。
+Docsy 以后增加的 locale 不会自动成为 OINK 支持项；它必须先补齐完整的 OINK
+词条，并接受与现有语言相同的审校。
+
+`i18n/en.yaml` 管理 192 键 schema。OINK 的 32 份语言包都必须拥有完全相同的键集
+与原生界面文本；只有经过审查的产品名、标点、通行缩写或目标语言真实同形词可以
+与英文保持相同，不再生成整段英文 fallback。`zh` 与 `zh-cn` 使用简体中文，
+`zh-tw` 使用繁体中文。
+
+在兼容下限 Hugo 0.160.x 上，如果同时存在地区化的中文语言包，作为非默认语言的
+通用 `zh` 语言键必须显式设置具体的 `locale: zh-CN`；从 Hugo 0.161 起，该配置也能
+解析裸 `locale: zh`。这项约束只影响语言配置，不改变语言包文件名 `i18n/zh.yaml`。
+
+`%s`、`{count}`、`{{ .Count }}` 等运行时占位符可以移到符合目标语言语法的位置，
+但字节内容必须保持不变。所有取值都是标量。语言包不得包含隐藏的双向文本控制符；
+阿拉伯语、波斯语和希伯来语的方向仍由消费站点的语言设置（`direction: rtl`）
+决定，不得把方向字符塞进译文。
+`bin/check-i18n.py` 会检查 locale 集合、schema、取值类型、占位符、方向控制符，
+以及少量已审查的英文本地同形词。因此增加可见字符串时，必须在同一变更中为每份
+语言包提供译文，不能再运行 fallback 生成器。
+
 ## 特色图片 {#featured-images}
 
 Hugo 的 `images` 是唯一的创作 API；`params.images` 只作为全站社交卡片回退。