OINK 1.5.0 — 译文并排阅读

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

OINK 1.5.0 为多语言站点新增按需开启的双语视图。读者、作者和译者可以把当前页面与已有 译文并排打开，让两侧保持在同一章节附近。该功能默认关闭，不开启的站点生成的页面与输出 保持不变。本文档站已升级至 OINK 1.5.0，并在 Docs 与博客页面默认开启双语视图——直接按 B 或点击本页右上角的「打开双语视图」按钮即可现场体验。

双语视图

只需一个站点参数即可开启：

params:
  ui:
    compare: true

只要 Docs、Book 或博客页面在同一站点下有已发布的 HTML 译文，页面动作栏旁就会出现 「打开双语视图」按钮；读者也可以从命令面板执行「双语视图」，或在开启键盘导航时按 B 打开。当前页面固定在阅读起始侧，另一侧窗格显示从目标语言菜单选中的 译文。

「同步滚动」会匹配两侧共同的可见标题 ID，并在相邻锚点之间平滑插值。即使某种语言篇幅 更长或中间多出小节，两侧也能按章节保持对应。如果只有部分标题匹配，阅读器会使用可用 锚点并显示近似同步提示；如果没有共同标题，则改按全文阅读进度估算位置。若标题 ID 重复 或在不同语言间顺序不一致，「同步滚动」会自动禁用，两侧仍可各自独立滚动阅读。按照 多语言指南在译文中保持一致的 {#id} 标题锚点， 可以获得最佳对齐效果。

双语视图只在读者打开时，通过同源 frame 加载现有的两篇 HTML 页面。每一栏完整保留各自的 语言、书写方向、标签页、表格、图表、脚注和交互组件，同时自动省去重复的顶栏/侧栏导航、 搜索、评论和统计脚本。构建时不会生成语言组合页面、新布局或额外输出格式；打印、Markdown 与订阅输出均保持不变。

响应式阅读与无障碍

屏幕宽度小于 900px 时，阅读器切换为紧凑工具栏加语言切换栏的单窗格布局，每次显示一个 窗格。切换栏同时整合了目标语言菜单，不再重复占用窗格标题行。即使在 320 × 256 CSS 像素 （约 400% 浏览器缩放）的紧凑视口下，正文区域仍能保留至少 160px 的可视高度，且不会出现 横向滚动条。

在从右向左（RTL）书写的页面上，当前页面固定在右侧（阅读起始侧），目标译文位于左侧。当窗口 尺寸跨过 900px 断点时，目标语言菜单会在桌面端栏头与移动端切换栏之间自动迁移，同时保留 键盘焦点、菜单展开状态和当前选中的窗格。强制颜色模式会用清晰边框标出当前活动窗格；只有在 启用键盘导航且页面存在可用译文时，才会暴露 B 快捷键、aria-keyshortcuts 属性及快捷键 帮助项。

语言范围与统计

如需让某个语言版本不参与双语对照，可在 languages.<lang>.params.ui 下设置 compare: false。该语言下的页面不会显示双语视图入口，也不会出现在其他页面的目标语言 菜单中。没有同源译文的页面、草稿、跳回语言首页的回退链接以及部署在其他域名的译文都会 自动排除。

通过 hooks/head-end.html 注入的自定义脚本会在每个窗格内执行。若在其中接入了访问统计， 请像统计与 SEO 所示，通过 window.OinkComparePane 在窗格中跳过上报。主题内置统计（services.googleAnalytics.id 与 params.analytics.*）会自动跳过对照窗格；启用 params.ui.compare: true 后，OINK 会 改用自带的窗格感知模板输出 Google Analytics，避免把两侧窗格重复计入浏览量，因此站点自定义 的 google_analytics.html partial 覆盖文件不再生效。

如果站点配置了内容安全策略（CSP），需要允许同源 frame（frame-src 'self'），并确保服务器 未发送阻止同源嵌入的 X-Frame-Options: DENY 或 frame-ancestors 'none'。详见 部署指南。

浏览器导航与历史记录

打开双语视图会写入一条浏览器历史记录。点击「关闭」、按 Escape 或使用浏览器 后退，都会关闭阅读器并恢复原页面的滚动位置与焦点。如果窗格内打开了图表查看器或展开表格 等内层弹窗，按 Escape 会先关闭内层弹窗，再关闭双语视图。

在双语视图打开时刷新页面，或通过浏览器前进回到该记录，都会在原有历史记录上重新打开阅读器， 不会重复压入新记录，因此始终只需后退一次即可回到普通阅读模式。窗格内的页内 #anchor 锚点会 在当前窗格内平滑跳转且不增加历史记录；点击站内其他页面链接会退出双语视图并正常跳转；外部链接 则在窗格外打开。

升级

使用 Hugo Extended 0.168.0 与 Go 1.27.3。主题样式继续使用 Hugo 内置 LibSass 编译。

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

提交更新后的 go.mod 与 go.sum。使用 vendor 或主题源码副本的站点需要单独刷新。保留 Hugo 的 LibSass 弃用告警并审阅其他诊断，不要启用 --panicOnWarning 或 HUGO_PANICONWARNING。

已有内容和配置无需迁移。新增界面文字已覆盖全部 32 套语言目录。升级指南 说明了验证、CSP、统计与回滚步骤。