OINK 1.1.0：原生多语言界面、导航与站点扩展

OINKOINK 项目本身作为正式发布注记与项目公告的作者。

OINK 1.1.0 是稳定 1.0 契约之后的第一个次版本：补齐原生界面翻译，让分类法根页 成为实用的导航目录，并处理社区对侧栏状态、键盘焦点、内容分组与搜索扩展的反馈。 现有 1.0 内容与配置不需要迁移源码。

概览

• 32 份原生界面目录：从 Docsy 继承的 31 个 locale 名称，加上通用 zh，均包含 相同的 194 条 OINK 消息，并采用各语言的复数规则。
• 分类法目录：标签、分类、作者与系列提供紧凑术语卡片、本地化页头，以及站点已 声明分类法之间的切换器。
• 可靠的导航：缓存侧栏保留页面设置，隐藏的侧栏退出焦点顺序，分组分区保留子文档。
• 站点扩展 API：OinkSidebar 提供已经提交的展开状态； OinkCommandPalette.registerSearchTail 支持使用当前查询的站点动作。
• 干净的文章复制：图片缩放不再向复制出的纯文本或 HTML 插入隐藏的预览提示。
• 正确的 Print 与预览输出：专用 Print 去除外壳导航，重叠的 Book 聚合不再竞态， 非法组件输入保留文档约定的回退行为。

原生界面与分类法目录

32 份 locale catalog 现在均使用原生 OINK 界面文本，不再包含机械生成的英文回退块。 页面计数交给 Hugo 按 CLDR 复数类别选择，覆盖需要多于单数、复数两种形式的语言。 目录检查涵盖缺失或多余的键、重复条目、占位符、复数形式与隐藏的双向文本控制字符。 这项工作翻译的是主题界面；站点正文仍由各站点自行提供译文。

/tags/、/categories/、/authors/ 与 /series/ 等分类法根页显示按使用量排序的 紧凑术语卡片网格。分类法页与术语页共用本地化页头，右栏可以切换到站点已声明的其它 分类法。作者卡片可以显示头像，具体术语页仍采用行列表归档。面包屑使用相同的本地化 分类法名称。

侧栏、分组与焦点

缓存侧栏现在遵循影响输出的页面与 cascade 有效设置；没有 JavaScript 时仍可导航， 恢复当前路径时也不会短暂降低对比度。带页面专属侧栏标题的 Book 页面不再复用共享 目录树缓存。

社区反馈对应四项修复：

• #41：关闭侧栏或抽屉后，隐藏内容不再接受 键盘焦点，也不再暴露给辅助技术。恢复按钮、桌面悬停展开、移动端焦点归还与 Escape 关闭继续正常工作。整列收起右侧大纲时，同样隔离内容并将焦点交给恢复按钮；移入移动 抽屉的分组仍可使用，不会继承桌面右栏的隐藏状态。抽屉的 Tab 循环只包含可见且可操作 的控件，闭合分支不会再让焦点漏到背后的正文。
• #42：sidebar_divider: true 将分区变成不带 链接的分组标签，同时保留子文档。配合 build.render: never 可不发布分组自身的 页面。面包屑不会生成分组死链接，搜索与翻页跳过分组，Print 与 Book 目录保留子文档。 无链接组头也参与目录树键盘导航：左方向键 / a 先返回组头，再折叠分组；右方向键 / d 先展开，再进入子项。q / e 仍只在页面链接间移动。显式导航树也能在带语言和 部署路径前缀时正确解析。
• #43：sidebar_root_menu: false 对顶层分区与 自根分区均生效。当前可链接的根仍作为位置标记显示；未发布分区与分隔分区不再生成 切换器链接。
• #44：鼠标点击阅读容器后，再按无关按键不会 突然出现大面积焦点边框；键盘导航与跳转正文链接继续保留可见焦点提示。

创作写法见内容分组，运行时行为见 侧栏契约。

站点自定义扩展

window.OinkSidebar 提供就绪 Promise、getState、setExpanded 与展开状态事件。 就绪信号会等缓存树恢复当前路径、响应式外壳完成分组安置后再发出，避免站点保存的状态 被后续初始化覆盖。OINK 先提交视觉状态、ARIA 与 inert 状态，再通知消费方。站点可以 通过该 API 保存读者选择的展开分支；存储方式、版本与语言策略由站点决定。恢复保存的 状态不会隐藏当前页面的祖先路径。

针对 #40，受信任的站点 JavaScript 可以通过 OinkCommandPalette.registerSearchTail({id, rows, activate}) 注册搜索尾部动作。 非空文本查询结束后，这些行显示在原生结果与动作之后，空结果与索引错误状态也可使用。 OINK 负责行渲染、激活、取消，并提供显式 handoff()，将焦点交给站点自己的界面。 异步动作尚未完成时，其它 Palette 行不能启动相互竞争的动作，包括打开选项列表的原生 命令；当前动作结束后解除激活限制。写法见集成示例。

两个 API 都是可选能力。现有站点采用本版本时不必增加脚本或修改配置。本地搜索仍默认 关闭，搜索扩展需要启用对应的 Palette；OINK 不内置远程助手、供应商凭据或查询遥测。

复制、Print 与组件修复

启用图片缩放时，旧版本会在每张符合条件的图片后插入视觉隐藏的预览提示。浏览器复制 可能把这些文字带进纯文本与富文本 HTML，目标编辑器丢弃主题样式后便会显示出来。 现在，缩放按钮通过 ARIA 名称提供图片描述与本地化动作，不再插入正文文字节点。 作者图片、alt、图注、键盘操作与对话框焦点归还均保留。修复覆盖普通图片与画廊的缩放 按钮，图片缩放仍默认关闭。详见图片缩放。

专用 Docs 与 Blog Print 输出不再包含站点顶栏或交互外壳初始化。每个页面由一个协调器 按固定顺序渲染普通输出与 Book 聚合输出，避免共享 Page Store 上的竞态，并保留各自 约定的标题与标签页 ID。

非法 book-toc drafts 值告警后继续使用文档约定的默认值。非字符串的 Landing preview.source 在普通预览中告警并仅省略该分区。Redoc 本地规范路径统一相对于 static/ 解析，在根路径与子路径部署下，无论开头是否带 / 都得到相同结果；有效的 远程 HTTP(S) URL 行为保持不变。

兼容性

Hugo Extended 0.160.1 仍是兼容性下限，持续集成固定工具链为 0.165.0。 模块与 1.0.0 一样声明 Go 1.27.0。Node 与 npm 用于文档回归套件，普通 Hugo 站点 构建不需要它们。

在 Hugo 0.160.x 上，非默认通用 zh 与区域中文目录并存时，需要配置 locale: zh-CN。在该组合中，裸 locale: zh 从 Hugo 0.161 起可用。阿拉伯语、波斯语 与希伯来语站点仍需为语言设置 direction: rtl。

从 1.0.0 升级无需迁移组件或配置。分类法根页的布局会有可见变化。覆盖过侧栏、分类法、 Print 或图片缩放实现的站点应与新版主题比较：复制到站点的实现不会自动获得上游修复。 兼容旧版本的站点脚本应先检测新 API 是否存在。

不再下发无效的 ScrollSpy 补丁。params.ui.scroll_spy 与页面级 scroll_spy 在整个 1.x 期间仍作为静默 no-op 接受；OINK 的普通大纲运行时已经跟踪当前标题。兼容 partial、受支持的搜索后端与迁移工具均继续保留。

验证与发布状态

实现提交 08f6563 已通过 固定工具链主题 CI 的 Hugo 检查、 浏览器运行时测试与 Book 出版检查。此前的社区修复验收，以及后续中英文图片复制回归， 记录在上游调研报告。补充的初始化、 动作并发与键盘焦点修复，以及源码验收记录在 发布审查报告。 本地验收通过 44 项 JavaScript 测试、57 项站点测试和 149 项 Chromium 测试。 Hugo Extended 0.160.1 也通过定向兼容性检查与真实文档站的严格生产构建。

输出检查器默认构建新 fixture，只有显式指定输出目录时才复用已有结果。检查器启动的 每个 Hugo 进程都有 120 秒上限；重复的 warning-fatal 构建已去除，逐例诊断与回退断言 仍然保留。

已发布的 v1.1.0 标签指向 3a18234， 该提交仅在已验收实现上收口更新日志，并通过全部三项 发布提交 CI。 通过全新缓存从官方 Go 模块代理 下载的版本准确解析到该提交；模块归档与 go.mod 的校验和均已通过 sum.golang.org 验证。

主题发布不会自动更新消费站。各站点仍需固定新模块，在没有文件系统替换的情况下 构建，并验证部署后的输出。

升级

固定公开版本并执行严格生产构建：

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings --panicOnWarning

提交 go.mod 与 go.sum，检查分类法目录、缓存与移动侧栏、分组导航、Print 与 Book 输出、文章复制，以及站点的语言、深浅色与子路径路由。操作清单见 1.0 → 1.1 升级核对项。

仓库级完整变更记录继续保存在 CHANGELOG.md。