lang.Translate
使用 i18n 目录中的翻译表返回翻译后的字符串。
这一页解决什么问题
模板里写死的界面文案(「阅读更多」「发表于」「隐私」)在多语言站点上是错的。lang.Translate 按键去 i18n/ 目录下的翻译表里取值:当前语言有就取当前语言,没有就回退到默认语言。它是多语言站点里唯一应该出现「界面文案」的地方——文本不写在模板里,而写在翻译表里。
别名有三个:T、i18n、lang.Translate,三者等价。
什么时候用,什么时候别用
该用:
- 界面文案(按钮、标签、提示语)与需要按语言变化的短文本;
- 需要复数形式(
1 day/2 days)的计数文案。
别用:
- 页面内容本身的多语言 → 用语言的页面包(
content/about.zh.md这类),不要塞进翻译表; - 想要一个可被站点配置覆盖的值 → 用
site.Params; - 想合并缺失译文的页面列表 → 用
lang.Merge。
lang.Translate 函数返回与给定键关联的值:先搜索当前语言的翻译表,再搜索 defaultContentLanguage 对应的翻译表。
若未找到,该函数返回空字符串。
翻译表
例如:
i18n/en.toml
i18n/pt-BR.tomlHugo 按以下基本名称(base name)依次查找匹配的翻译表:
- 当前语言的
locale - 当前语言的 key
defaultContentLanguage的 localedefaultContentLanguage的 key
也支持 RFC 5646 § 2.2.7 中定义的、带私有子标签(private use subtag)的人造语言。为简洁起见,可以省略 art-x- 前缀。例如:
i18n/art-x-hugolang.toml
i18n/hugolang.toml简单翻译
假设你的多语言项目支持两种语言:英语和波兰语。请在 i18n 目录中为每种语言创建一个翻译表。
i18n/
├── en.toml
└── pl.toml英语翻译表:
privacy = 'privacy'
security = 'security'波兰语翻译表:
privacy = 'prywatność'
security = 'bezpieczeństwo'查看英语站点时:
{{ T "privacy" }} → privacy
{{ T "security" }} → security查看波兰语站点时:
{{ T "privacy" }} → prywatność
{{ T "security" }} → bezpieczeństwo带复数形式的翻译
假设你的多语言项目支持两种语言:英语和波兰语。请在 i18n 目录中为每种语言创建一个翻译表。
i18n/
├── en.toml
└── pl.tomlUnicode 的 CLDR 复数规则表 描述了各语言的复数类别。
英语翻译表:
[day]
one = 'day'
other = 'days'
[day_with_count]
one = '{{ . }} day'
other = '{{ . }} days'波兰语翻译表:
[day]
one = 'miesiąc'
few = 'miesiące'
many = 'miesięcy'
other = 'miesiąca'
[day_with_count]
one = '{{ . }} miesiąc'
few = '{{ . }} miesiące'
many = '{{ . }} miesięcy'
other = '{{ . }} miesiąca'查看英语站点时:
{{ T "day" 0 }} → days
{{ T "day" 1 }} → day
{{ T "day" 2 }} → days
{{ T "day" 5 }} → days
{{ T "day_with_count" 0 }} → 0 days
{{ T "day_with_count" 1 }} → 1 day
{{ T "day_with_count" 2 }} → 2 days
{{ T "day_with_count" 5 }} → 5 days查看波兰语站点时:
{{ T "day" 0 }} → miesięcy
{{ T "day" 1 }} → miesiąc
{{ T "day" 2 }} → miesiące
{{ T "day" 5 }} → miesięcy
{{ T "day_with_count" 0 }} → 0 miesięcy
{{ T "day_with_count" 1 }} → 1 miesiąc
{{ T "day_with_count" 2 }} → 2 miesiące
{{ T "day_with_count" 5 }} → 5 miesięcy在上面的复数示例中,我们在上下文中传入了一个整数(第二个参数)。你也可以在上下文中传入一个 map,并提供 count 键来控制复数形式。
翻译表:
[age]
one = '{{ .name }} is {{ .count }} year old.'
other = '{{ .name }} is {{ .count }} years old.'模板代码:
{{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old.
{{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old.保留键
Hugo 使用 nicksnyder/go-i18n 包在翻译表中查找值。该包为内部用途保留了以下键:
id- (
string)唯一标识该消息。 description- (
string)描述该消息,为译者提供可能有用的补充上下文。 hash- (
string)唯一标识该消息所翻译自的原文内容。 leftdelim- (
string)Go 模板的左定界符。 rightdelim- (
string)Go 模板的右定界符。 zero- (
string)CLDR 复数形式 “zero” 对应的消息内容。 one- (
string)CLDR 复数形式 “one” 对应的消息内容。 two- (
string)CLDR 复数形式 “two” 对应的消息内容。 few- (
string)CLDR 复数形式 “few” 对应的消息内容。 many- (
string)CLDR 复数形式 “many” 对应的消息内容。 other- (
string)CLDR 复数形式 “other” 对应的消息内容。
如果需要为某个保留键提供译文,可以在该词前加下划线。例如:
_description = 'descripción'
_few = 'pocos'
_many = 'muchos'
_one = 'uno'
_other = 'otro'
_two = 'dos'
_zero = 'cero'然后在模板中:
{{ T "_description" }} → descripción
{{ T "_few" }} → pocos
{{ T "_many" }} → muchos
{{ T "_one" }} → uno
{{ T "_two" }} → dos
{{ T "_zero" }} → cero
{{ T "_other" }} → otro完整示例(实测)
测量站点:defaultContentLanguage='en',语言 en(locale='en-US')与 zh(locale='zh-CN');i18n/en.toml 与 i18n/zh.toml 内容如下(zh.toml 只提供 privacy、security 与 day/day_with_count 的 other 形式)。
privacy = 'privacy'
security = 'security'
[day]
one = 'day'
other = 'days'
[day_with_count]
one = '{{ . }} day'
other = '{{ . }} days'
[age]
one = '{{ .name }} is {{ .count }} year old.'
other = '{{ .name }} is {{ .count }} years old.'[{{ T "privacy" }}]|[{{ i18n "security" }}]|[{{ T "day" 1 }}]|[{{ T "day" 2 }}]|[{{ T "no_such_key" }}]Hugo 0.167.0 实测输出,en 站点:
[privacy]|[security]|[day]|[days]|[]zh 站点(同一段模板):
[隐私]|[安全]|[1 天]|[2 天]|[]你应当看到什么:T/i18n/lang.Translate 三种写法取到同一个值;复数按计数选择 one/other;zh 站点在 zh.toml 里只写了 other,所以 T "day" 1 也得 1 天;不存在的 key 得到空字符串(最后一对方括号里什么都没有)。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;双语站点,翻译表如上一节。
| 情况 | 结果 | 是否报错 |
|---|---|---|
当前语言有该 key(实测 T "privacy") |
该语言的译文(en 得 privacy,zh 得 隐私) |
否 |
当前语言缺该 key、默认语言有(实测 zh 站点的 T "age") |
回退到默认语言的译文:实测返回英文 Will is 1 year old. |
否 |
两种语言都没有该 key(实测 T "no_such_key") |
""(空字符串) |
否——静默返回空串 |
整数上下文(实测 T "day" 0/1/2/5) |
en:days/day/days/days;zh(只有 other):0 天/1 天/2 天/5 天 |
否 |
map 上下文(实测 T "age" (dict "name" "Will" "count" 1)) |
Will is 1 year old.(count 控制复数) |
否 |
| 返回类型 | string,永远不是 nil |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 页面上少了一段文字,控制台没有任何提示 | 缺失的 key 返回空字符串、不报错(实测) | 用 --printI18nWarnings 列出缺失项;或给 key 起名时统一前缀便于排查 |
| 没报错但结果不对 | 中文站点显示英文 | zh.toml 里没有这个 key,回退到了默认语言(实测) |
在 zh.toml 里补上该 key |
| 没报错但结果不对 | 复数形式不对 | 翻译表里缺少该语言需要的 CLDR 复数类别(例如中文只需要 other,波兰语需要 one/few/many/other) |
对照 CLDR 复数规则表 补齐类别 |
| 没报错但结果不对 | 翻译表根本没被读取 | 文件名与语言不匹配:Hugo 依次按当前语言的 locale、语言 key、默认语言的 locale、默认语言的 key 查找(见上文「翻译表」) |
把文件名改成与语言配置一致的 i18n/zh.toml / i18n/en.toml |
| 没报错但结果不对 | 占位符没有被替换 | 复数消息里的 {{ . }} 需要传入上下文(整数或带 count 的 map) |
调用时带上第二个参数 |
更多排查入口见故障排查。