Translations
返回给定页面的所有译文(不含当前语言),按语言权重再按语言名称排序。
这一页解决什么问题
「本文还有哪些语言版本?」——.Translations 返回除当前语言之外的所有译文页面,用 range 就能渲染语言列表:
go-html-template
{{ with .Translations }}
<ul>{{ range . }}<li><a href="{{ .RelPermalink }}">{{ .Language.Lang }}</a></li>{{ end }}</ul>
{{ end }}它和 .Rotate "language" 的差别只有一处:.Translations 不含当前语言,.Rotate 含。做「切换到其他语言」用 .Translations;做「语言切换器(含当前项高亮)」用 .Rotate。
什么时候用,什么时候别用
该用:
- 「其他语言版本」链接列表、
hreflang链接; - 需要「这一页有没有别的语言」时(配合
with,空集合走else)。
别用:
- 想做含当前语言的语言切换器 → 用
.Rotate "language"; - 想知道「有没有译文」这一个布尔问题 → 用
.IsTranslated; - 想列出所有语言站点(不管这一页有没有译文)→ 用
hugo.Sites。
对照(实测,本站 en + zh):
| 页面 | .Translations |
.Rotate "language" |
|---|---|---|
/posts/post-2/(有中文版) |
zh → /posts/post-2/ |
en、zh |
/docs/ref/(没有中文版) |
空(with 走 else) |
只有 en |
用法
项目配置如下:
toml
defaultContentLanguage = 'en'
[languages.en]
contentDir = 'content/en'
label = 'English'
locale = 'en-US'
weight = 1
[languages.de]
contentDir = 'content/de'
label = 'Deutsch'
locale = 'de-DE'
weight = 2
[languages.fr]
contentDir = 'content/fr'
label = 'Français'
locale = 'fr-FR'
weight = 3内容如下:
tree
content/
├── de/
│ ├── books/
│ │ ├── book-1.md
│ │ └── book-2.md
│ └── _index.md
├── en/
│ ├── books/
│ │ ├── book-1.md
│ │ └── book-2.md
│ └── _index.md
├── fr/
│ ├── books/
│ │ └── book-1.md
│ └── _index.md
└── _index.md模板如下:
go-html-template
{{ with .Translations }}
<ul>
{{ range . }}
<li>
<a href="{{ .RelPermalink }}" hreflang="{{ .Language.Locale }}">{{ .LinkTitle }} ({{ or .Language.Label .Language.Name }})</a>
</li>
{{ end }}
</ul>
{{ end }}在英文站点的 book-1 页面上,Hugo 会渲染出这个列表:
html
<ul>
<li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
<li><a href="/fr/books/book-1/" hreflang="fr-FR">Book 1 (Français)</a></li>
</ul>在英文站点的 book-2 页面上,Hugo 会渲染出这个列表:
html
<ul>
<li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
</ul>完整示例:其他语言版本
测试站配置:
toml
defaultContentLanguage = 'en'
[languages.en]
weight = 1
title = 'MP EN'
label = 'English'
locale = 'en-US'
[languages.zh]
weight = 2
title = 'MP ZH'
label = '中文'
locale = 'zh-CN'模板(layouts/_default/single.html):
layouts/_default/single.htmlgo-html-template
{{ with .Translations }}
<ul class="translations">
{{ range . }}
<li><a href="{{ .RelPermalink }}" hreflang="{{ .Language.Locale }}">{{ .Language.Lang }}</a></li>
{{ end }}
</ul>
{{ else }}
<p>本文暂无其他语言版本</p>
{{ end }}实测(Hugo 0.167.0):
| 渲染的页面 | 渲染结果 |
|---|---|
/posts/post-1/(英文,有 post-1.zh.md) |
<ul class="translations"><li><a href="/zh/posts/post-1/" hreflang="zh-CN">zh</a></li></ul> |
/zh/posts/post-1/(中文) |
<ul class="translations"><li><a href="/posts/post-1/" hreflang="en-US">en</a></li></ul> |
/docs/ref/(没有中文版) |
<p>本文暂无其他语言版本</p> |
你应当看到什么:英文页只列出 zh(不含自己),中文页只列出 en;没有译文的页面得到空集合,with 会走 else。所以 .Translations 天然是「安全的」——不需要额外判空就能用,但仍建议用 with 给出兜底文案。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 有译文 | 译文页面集合,不含当前语言(实测) | 否 |
| 没有译文 | 空集合,with/if 为假(实测 /docs/ref/) |
否 |
| 排序 | 按语言 weight,其次按语言名称(上游说明) | 否 |
| 单语言站点 | 空集合 | 否 |
| 返回类型 | page.Pages(可 range) |
否 |
更多排查入口见故障排查。