# OINK 1.5.0 — 译文并排阅读

> 按需开启双语视图，把页面与译文并排阅读，并按共同标题同步滚动。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

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

**v1\.5\.0 · 2026-11-04**
- [查看发布](https://github.com/pgsty/oink/releases/tag/v1.5.0)
- [源码 · tar\.gz](https://github.com/pgsty/oink/archive/refs/tags/v1.5.0.tar.gz)
- [源码 · zip](https://github.com/pgsty/oink/archive/refs/tags/v1.5.0.zip)
- [pgsty\/oink](https://github.com/pgsty/oink)

## 双语视图 {#bilingual-view}

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

```yaml {title="hugo.yaml"}
params:
  ui:
    compare: true
```

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

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

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

## 响应式阅读与无障碍 {#narrow}

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

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

## 语言范围与统计 {#before-enabling}

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

通过 `hooks/head-end.html` 注入的自定义脚本会在每个窗格内执行。若在其中接入了访问统计，
请像[统计与 SEO](/zh/docs/admin/analytics/#bilingual-view) 所示，通过
`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'`。详见
[部署指南](/zh/docs/admin/deploy/#csp)。

## 浏览器导航与历史记录 {#history}

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

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

## 升级 {#upgrade}

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

```sh
hugo mod get github.com/pgsty/oink@v1.5.0
hugo mod tidy
hugo --environment production --minify --printPathWarnings
```

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

已有内容和配置无需迁移。新增界面文字已覆盖全部 32 套语言目录。[升级指南](/zh/docs/admin/upgrade/#preparing-1-5)
说明了验证、CSP、统计与回滚步骤。

---

反链：

- [发布](/zh/blog/release/)
- [文档](/zh/docs/)
- [简介](/zh/docs/about/)
- [参与贡献](/zh/docs/about/contributing/)
- [版本升级](/zh/docs/admin/upgrade/)