Page

TranslationKey

返回给定页面的翻译 key。

签名
PAGE.TranslationKey
返回类型
string

这一页解决什么问题

多语言站点里,Hugo 需要知道「英文的 book-1.md 和德文的 buch-1.md 是同一篇文章」。这个身份就是翻译 key,.TranslationKey 返回它。默认由文件路径推导——所以中英文同名文件(post-1.md 与 post-1.zh.md)自动配对;文件名不同时,用 front matter 的 translationKey 手工绑定。

配对的直接用途是 .Translations(列出其他语言版本)和语言切换器。

什么时候用,什么时候别用

该用:

  • 调试「为什么这两个页面没有互相识别为翻译」;
  • 需要自己按翻译 key 分组页面(例如 where 或 dict 归类各语言版本);
  • 校验内容结构(同一 key 应在各语言下各出现一次)。

别用:

用法

翻译 key 在给定页面的所有译文之间建立关联。翻译 key 由文件路径推导而来;如果前置元数据中定义了 translationKey 参数,则由该参数决定。

项目配置如下:

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

内容如下:

tree
content/
├── de/
│   ├── books/
│   │   ├── buch-1.md
│   │   └── book-2.md
│   └── _index.md
├── en/
│   ├── books/
│   │   ├── book-1.md
│   │   └── book-2.md
│   └── _index.md
└── _index.md

前置元数据如下:

toml
title = 'Book 1'
translationKey = 'foo'
toml
title = 'Buch 1'
translationKey = 'foo'

渲染上述任一页面时:

go-html-template
{{ .TranslationKey }} → page/foo

如果两种语言中 Book 2 的前置元数据都没有包含翻译 key:

go-html-template
{{ .TranslationKey }} → page/books/book-2

完整示例:文件名配对与手工配对

测试站有两种语言(en、zh),内容文件采用同目录同文件名 + 语言后缀的方式:

tree
content/posts/
├── post-1.md        <-- 英文
├── post-1.zh.md     <-- 中文(自动配对)
├── post-2.md        <-- 英文,front matter: translationKey = 'shared'
└── post-2.zh.md     <-- 中文,front matter: translationKey = 'shared'

模板(layouts/_default/single.html):

layouts/_default/single.htmlgo-html-template
<p>{{ .TranslationKey }}</p>

实测(Hugo 0.167.0):

渲染的页面 是否写了 translationKey .TranslationKey
/posts/post-1/ 否 /posts/post-1
/zh/posts/post-1/ 否 /posts/post-1(与英文版相同)
/posts/post-2/ 是(shared) shared
/zh/posts/post-2/ 是(shared) shared

你应当看到什么:同名的中英文页面自动得到同一个 key(逻辑路径,不含语言段),所以不需要手工配置;文件名不同时(如 book-1 / buch-1)才需要 front matter 里的 translationKey 把它们绑到一起。

返回值边界(实测)

情况 结果 是否报错
未写 translationKey 页面逻辑路径(实测 /posts/post-1) 否
写了 translationKey 该值原样(实测 shared,无 page/ 前缀) 否
不同语言、相同文件名 返回相同值(实测中英文均为 /posts/post-1) 否
不同语言、不同文件名 默认不配对;需要 translationKey 显式绑定 否
返回类型 string 否

更多排查入口见故障排查。