Language
返回给定站点的 Language 对象。
这一页解决什么问题
Language 返回当前站点的语言对象:这个站点是哪种语言(Name)、使用什么 locale(Locale)、显示名是什么(Label)、书写方向是什么(Direction),以及它是不是默认语言(IsDefault)。
它最常见的用途只有一个:在 base 模板里给 <html> 写 lang 与 dir 属性。多语言站点里,每个语言会各自渲染一遍模板,.Site.Language 就是「现在轮到哪个语言」的答案。
什么时候用,什么时候别用
该用:
<html lang="…" dir="…">、hreflang、feed 的<language>一类语言元信息;- 需要按语言分支显示文案时判断
Name或IsDefault。
别用:
- 用已弃用的
Lang、LanguageCode、LanguageName、LanguageDirection(0.158.0 起弃用),它们分别对应Name、Locale、Label、Direction; - 想遍历项目里所有语言 → 用
Site.Languages(已弃用)或hugo.Sites; - 想取站点标题 → 用
Site.Title,语言对象的Label是语言显示名,不是站点标题; - 页面自己的语言 → 用页面上的
Language方法(见 methods/page)。
方法
在 Language 对象上使用这些方法。
下面的示例都基于如下语言定义。
toml
[languages.de]
direction = 'ltr'
label = 'Deutsch'
locale = 'de-DE'
weight = 2Direction- (0.158.0 新增)
- (
string)返回语言定义中的direction。go-html-template{{ .Site.Language.Direction }} → ltr IsDefault- (0.153.0 新增)
- (
bool)报告这是否为默认语言。go-html-template{{ .Site.Language.IsDefault }} → true Label- (0.158.0 新增)
- (
string)返回语言定义中的label。go-html-template{{ .Site.Language.Label }} → Deutsch Lang- (0.158.0 起弃用)
- 请改用
Name。 LanguageCode- (0.158.0 起弃用)
- 请改用
Locale。 LanguageDirection- (0.158.0 起弃用)
- 请改用
Direction。 LanguageName- (0.158.0 起弃用)
- 请改用
Label。 Locale- (0.158.0 新增)
- (
string)返回语言定义中的locale,找不到时回退到Name。go-html-template{{ .Site.Language.Locale }} → de-DE Name- (0.153.0 新增)
- (
string)返回由 RFC 5646 定义的语言标签,即语言定义中转为小写的键名。go-html-template{{ .Site.Language.Name }} → de Weight- (0.158.0 起弃用)
示例
上面的一些方法常用于 base 模板,作为 html 元素的属性。
go-html-template
<html
lang="{{ .Site.Language.Locale }}"
dir="{{ or .Site.Language.Direction `ltr` }}"
>完整示例(实测)
单语言站点若不写 [languages],只有 Name 与 Locale 有确定值:
layouts/index.htmlgo-html-template
<p>Name:{{ .Site.Language.Name }}</p>
<p>Locale:{{ .Site.Language.Locale }}</p>
<p>Label:[{{ .Site.Language.Label }}]</p>
<p>Direction:[{{ .Site.Language.Direction }}]</p>
<p>IsDefault:{{ .Site.Language.IsDefault }}</p>一个 locale = 'en-US'、未定义 [languages] 的站点实测渲染为:
html
<p>Name:en</p>
<p>Locale:en-US</p>
<p>Label:[]</p>
<p>Direction:[]</p>
<p>IsDefault:true</p>多语言站点([languages.de] 与 [languages.en] 都写了 label、locale、direction)里,同一模板在德语站点实测渲染为:
html
<p>Name:de</p>
<p>Locale:de-DE</p>
<p>Label:[Deutsch]</p>
<p>Direction:[ltr]</p>
<p>IsDefault:false</p>你应当看到什么:Label 与 Direction 是配置里写了才有的字段(没写就是空字符串,不报错),而 Name 与 Locale 总有值。所以 base 模板里的 dir 要像上游示例那样用 or … \ltr`` 兜底。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;分别在单语言站点与含 [languages.de]、[languages.en] 的站点测量。
| 情况 | 结果 | 是否报错 |
|---|---|---|
未配置 [languages],locale = 'en-US' |
Name → en,Locale → en-US,IsDefault → true |
否 |
未配置 label / direction |
Label、Direction 均为空字符串 |
否 |
配置了 label = 'Deutsch' / direction = 'ltr' |
原样返回 | 否 |
| 非默认语言站点 | IsDefault → false |
否 |
弃用的 Lang / LanguageCode |
实测仍分别返回 en / en-US(可用但不应用新代码) |
否 |
printf "%T" .Site.Language |
*langs.Language |
否 |