多语言模式
配置语言
这是默认的语言配置
languages:
en:
disabled: false
languageCode: ""
languageDirection: ""
languageName: ""
title: ""
weight: 0
[languages]
[languages.en]
disabled = false
languageCode = ''
languageDirection = ''
languageName = ''
title = ''
weight = 0
{
"languages": {
"en": {
"disabled": false,
"languageCode": "",
"languageDirection": "",
"languageName": "",
"title": "",
"weight": 0
}
}
}
在上述配置中,en
是语言键。
语言键必须符合 RFC 5646 中描述的语法。例如
en
en-US
也支持在 RFC 5646 § 2.2.7 中定义的使用私有子标签的人工语言。从语言键中省略 art-x-
前缀。例如
hugolang
这是一个多语言项目的站点配置示例。在 languages
对象中未定义的任何键都将回退到站点配置根目录中的全局值。
defaultContentLanguage: de
defaultContentLanguageInSubdir: true
languages:
de:
contentDir: content/de
disabled: false
languageCode: de-DE
languageDirection: ltr
languageName: Deutsch
params:
subtitle: Referenz, Tutorials und Erklärungen
title: Projekt Dokumentation
weight: 1
en:
contentDir: content/en
disabled: false
languageCode: en-US
languageDirection: ltr
languageName: English
params:
subtitle: Reference, Tutorials, and Explanations
title: Project Documentation
weight: 2
defaultContentLanguage = 'de'
defaultContentLanguageInSubdir = true
[languages]
[languages.de]
contentDir = 'content/de'
disabled = false
languageCode = 'de-DE'
languageDirection = 'ltr'
languageName = 'Deutsch'
title = 'Projekt Dokumentation'
weight = 1
[languages.de.params]
subtitle = 'Referenz, Tutorials und Erklärungen'
[languages.en]
contentDir = 'content/en'
disabled = false
languageCode = 'en-US'
languageDirection = 'ltr'
languageName = 'English'
title = 'Project Documentation'
weight = 2
[languages.en.params]
subtitle = 'Reference, Tutorials, and Explanations'
{
"defaultContentLanguage": "de",
"defaultContentLanguageInSubdir": true,
"languages": {
"de": {
"contentDir": "content/de",
"disabled": false,
"languageCode": "de-DE",
"languageDirection": "ltr",
"languageName": "Deutsch",
"params": {
"subtitle": "Referenz, Tutorials und Erklärungen"
},
"title": "Projekt Dokumentation",
"weight": 1
},
"en": {
"contentDir": "content/en",
"disabled": false,
"languageCode": "en-US",
"languageDirection": "ltr",
"languageName": "English",
"params": {
"subtitle": "Reference, Tutorials, and Explanations"
},
"title": "Project Documentation",
"weight": 2
}
}
}
- defaultContentLanguage
- (
string
)项目默认的语言键,符合 RFC 5646 中描述的语法。此值必须与定义的语言键之一匹配。示例
en
en-GB
pt-BR
- defaultContentLanguageInSubdir
- (
bool
)如果为true
,Hugo 将在与defaultContentLanguage
匹配的子目录中渲染默认语言站点。默认为false
。 - contentDir
- (
string
)此语言的content
目录。如果 按文件名翻译,则省略此项。 - disabled
- (
bool
)如果为true
,Hugo 将不会为此语言渲染内容。默认为false
。 - languageCode
- (
string
)RFC 5646 中描述的语言标签。此值不影响本地化或 URL。Hugo 使用此值填充 内置 RSS 模板中的language
元素,以及 内置别名模板中html
元素的lang
属性。示例
en
en-GB
pt-BR
- languageDirection
- (
string
)语言方向,要么是从左到右 (ltr
) 要么是从右到左 (rtl
)。在你的模板中使用此值,结合全局dir
HTML 属性。 - languageName
- (
string
)语言名称,通常在渲染语言切换器时使用。 - title
- (
string
)此语言的站点标题(可选)。 - weight
- (
int
)语言权重。当设置为非零值时,这是此语言的主要排序条件。
Hugo 0.112.0 中的更改
v0.112.0 中的新增功能在 Hugo v0.112.0
中,我们整合了所有配置选项,并改进了语言及其参数与主配置合并的方式。但在在 Hugo 站点上进行测试时,我们收到了一些错误报告,并为了兼容性,将一些更改恢复为弃用警告
site.Language.Params
已弃用。直接使用site.Params
。- 向顶级语言配置添加自定义参数已弃用。在
languages.xx.params
中定义自定义参数。请参见下面的示例中的color
。
languageCode: en-us
languages:
en:
params:
color: blue
sv:
languageCode: sv
title: Min blogg
title: My blog
languageCode = 'en-us'
title = 'My blog'
[languages]
[languages.en]
[languages.en.params]
color = 'blue'
[languages.sv]
languageCode = 'sv'
title = 'Min blogg'
{
"languageCode": "en-us",
"languages": {
"en": {
"params": {
"color": "blue"
}
},
"sv": {
"languageCode": "sv",
"title": "Min blogg"
}
},
"title": "My blog"
}
在上面的示例中,params
下的所有设置(除了 color
)都映射到 Hugo 中预定义的站点及其语言的配置选项,应该通过文档中记录的访问器访问
{{ site.Title }}
{{ site.Language.LanguageCode }}
{{ site.Params.color }}
禁用语言
在站点配置的 languages
对象中禁用语言
languages:
es:
disabled: true
[languages]
[languages.es]
disabled = true
{
"languages": {
"es": {
"disabled": true
}
}
}
在站点配置的根目录中禁用一种或多种语言
disableLanguages:
- es
- fr
disableLanguages = ['es', 'fr']
{
"disableLanguages": [
"es",
"fr"
]
}
使用环境变量禁用一种或多种语言
HUGO_DISABLELANGUAGES="es fr" hugo
请注意,您不能禁用默认内容语言。
配置多语言多主机
Hugo 支持多主机配置中的多种语言。这意味着您可以为每个 language
配置一个 baseURL
。
示例
languages:
en:
baseURL: https://en.example.org/
languageName: English
title: In English
weight: 2
fr:
baseURL: https://fr.example.org
languageName: Français
title: En Français
weight: 1
[languages]
[languages.en]
baseURL = 'https://en.example.org/'
languageName = 'English'
title = 'In English'
weight = 2
[languages.fr]
baseURL = 'https://fr.example.org'
languageName = 'Français'
title = 'En Français'
weight = 1
{
"languages": {
"en": {
"baseURL": "https://en.example.org/",
"languageName": "English",
"title": "In English",
"weight": 2
},
"fr": {
"baseURL": "https://fr.example.org",
"languageName": "Français",
"title": "En Français",
"weight": 1
}
}
}
使用以上配置,这两个站点将被生成到 public
目录中,并拥有自己的根目录
public
├── en
└── fr
所有 URL(即 .Permalink
等)都将从该根目录生成。因此,上面的英文主页的 .Permalink
将设置为 https://example.org/
。
当您运行 hugo server
时,我们会启动多个 HTTP 服务器。您通常会在控制台中看到类似以下的内容:
Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) fr
Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) en
Press Ctrl+C to stop
服务器之间的实时重新加载和 --navigateToChanged
功能都可以按预期工作。
翻译您的内容
有两种方式来管理您的内容翻译。两种方式都可以确保每个页面都被分配一种语言,并链接到其对应的翻译版本。
通过文件名翻译
考虑以下示例:
/content/about.en.md
/content/about.fr.md
第一个文件被分配为英语,并链接到第二个文件。第二个文件被分配为法语,并链接到第一个文件。
它们的语言是根据添加到**文件名的后缀**的语言代码进行**分配**的。
通过具有相同的**路径和基础文件名**,这些内容片段被**链接**在一起,作为翻译页面。
通过内容目录翻译
此系统为每种语言使用不同的内容目录。每种语言的 content
目录都使用 contentDir
参数设置。
languages:
en:
contentDir: content/english
languageName: English
weight: 10
fr:
contentDir: content/french
languageName: Français
weight: 20
[languages]
[languages.en]
contentDir = 'content/english'
languageName = 'English'
weight = 10
[languages.fr]
contentDir = 'content/french'
languageName = 'Français'
weight = 20
{
"languages": {
"en": {
"contentDir": "content/english",
"languageName": "English",
"weight": 10
},
"fr": {
"contentDir": "content/french",
"languageName": "Français",
"weight": 20
}
}
}
contentDir
的值可以是任何有效的路径,甚至是绝对路径引用。唯一的限制是内容目录不能重叠。
结合上面的配置,考虑以下示例:
/content/english/about.md
/content/french/about.md
第一个文件被分配为英语,并链接到第二个文件。第二个文件被分配为法语,并链接到第一个文件。
它们的语言是根据它们**放置**的 content
目录进行**分配**的。
通过具有相同的**路径和基本名称**(相对于它们各自的语言 content
目录),这些内容片段被**链接**在一起,作为翻译页面。
绕过默认链接
任何在前置元数据中设置了相同 translationKey
的页面,都将被链接为翻译页面,无论其基本名称或位置如何。
考虑以下示例:
/content/about-us.en.md
/content/om.nn.md
/content/presentation/a-propos.fr.md
translationKey: about
translationKey = 'about'
{
"translationKey": "about"
}
通过在所有三个页面中将 translationKey
前置元数据参数设置为 about
,它们将被**链接**为翻译页面。
本地化永久链接
由于路径和文件名用于处理链接,因此所有翻译页面将共享相同的 URL(除了语言子目录)。
要本地化 URL:
例如,法语翻译可以有自己的本地化 slug。
---
slug: a-propos
title: A Propos
---
+++
slug = 'a-propos'
title = 'A Propos'
+++
{
"slug": "a-propos",
"title": "A Propos"
}
在渲染时,Hugo 将构建 /about/
和 /fr/a-propos/
,而不会影响翻译链接。
页面包
为了避免重复文件的负担,每个页面包都继承其链接的翻译页面包的资源,除了内容文件(Markdown 文件、HTML 文件等)。
因此,从模板内部,页面将可以访问所有链接页面的包中的文件。
如果,在链接的包中,两个或多个文件共享相同的基础名称,则只会包含一个文件,并按以下方式选择:
- 如果存在,则来自当前语言包的文件。
- 按语言
Weight
顺序在包中找到的第一个文件。
引用翻译内容
要创建指向翻译内容的链接列表,请使用类似于以下的模板:
{{ if .IsTranslated }}
<h4>{{ i18n "translations" }}</h4>
<ul>
{{ range .Translations }}
<li>
<a href="{{ .RelPermalink }}">{{ .Language.Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
</li>
{{ end }}
</ul>
{{ end }}
以上内容可以放在一个 partial
中(例如,在 layouts/partials/
中),并包含在任何模板中。如果没有给定页面的翻译,它将不会打印任何内容。
以上内容还使用了下一节中描述的 i18n
函数。
列出所有可用的语言
Page
上的 .AllTranslations
可用于列出所有翻译,包括页面本身。在主页上,它可用于构建语言导航器
<ul>
{{ range $.Site.Home.AllTranslations }}
<li><a href="{{ .RelPermalink }}">{{ .Language.LanguageName }}</a></li>
{{ end }}
</ul>
字符串翻译
请参阅 lang.Translate
模板函数。
本地化
以下本地化示例假设您的网站的主要语言是英语,并翻译为法语和德语。
defaultContentLanguage: en
languages:
de:
contentDir: content/de
languageName: Deutsch
weight: 3
en:
contentDir: content/en
languageName: English
weight: 1
fr:
contentDir: content/fr
languageName: Français
weight: 2
defaultContentLanguage = 'en'
[languages]
[languages.de]
contentDir = 'content/de'
languageName = 'Deutsch'
weight = 3
[languages.en]
contentDir = 'content/en'
languageName = 'English'
weight = 1
[languages.fr]
contentDir = 'content/fr'
languageName = 'Français'
weight = 2
{
"defaultContentLanguage": "en",
"languages": {
"de": {
"contentDir": "content/de",
"languageName": "Deutsch",
"weight": 3
},
"en": {
"contentDir": "content/en",
"languageName": "English",
"weight": 1
},
"fr": {
"contentDir": "content/fr",
"languageName": "Français",
"weight": 2
}
}
}
日期
使用此前端元数据
date: 2021-11-03T12:34:56+01:00
date = 2021-11-03T12:34:56+01:00
{
"date": "2021-11-03T12:34:56+01:00"
}
以及此模板代码
{{ .Date | time.Format ":date_full" }}
渲染后的页面显示:
语言 | 值 |
---|---|
英语 | 2021 年 11 月 3 日,星期三 |
法语 | 2021 年 11 月 3 日,星期三 |
德语 | 2021 年 11 月 3 日,星期三 |
有关详细信息,请参阅 time.Format
。
货币
使用此模板代码
{{ 512.5032 | lang.FormatCurrency 2 "USD" }}
渲染后的页面显示:
语言 | 值 |
---|---|
英语 | $512.50 |
法语 | 512.50 美元 |
德语 | 512,50 $ |
有关详细信息,请参阅 lang.FormatCurrency 和 lang.FormatAccounting。
数字
使用此模板代码
{{ 512.5032 | lang.FormatNumber 2 }}
渲染后的页面显示:
语言 | 值 |
---|---|
英语 | 512.50 |
法语 | 512,50 |
德语 | 512,50 |
有关详细信息,请参阅 lang.FormatNumber 和 lang.FormatNumberCustom。
百分比
使用此模板代码
{{ 512.5032 | lang.FormatPercent 2 }}
渲染后的页面显示:
语言 | 值 |
---|---|
英语 | 512.50% |
法语 | 512,50 % |
德语 | 512,50 % |
有关详细信息,请参阅 lang.FormatPercent。
菜单
菜单条目的本地化取决于您如何定义它们
- 当您使用节页面菜单 自动定义菜单条目时,必须使用翻译表来本地化每个条目。
- 当您在前置元数据中定义菜单条目时,它们已经基于前置元数据本身进行本地化。如果前置元数据值不足,请使用翻译表来本地化每个条目。
- 当您在站点配置中定义菜单条目时,必须在每个语言键下创建特定于语言的菜单条目。如果菜单条目的名称不足,请使用翻译表来本地化每个条目。
创建特定于语言的菜单条目
方法 1 – 使用单个配置文件
对于条目数量较少的简单菜单,请使用单个配置文件。例如:
languages:
de:
languageCode: de-DE
languageName: Deutsch
menus:
main:
- name: Produkte
pageRef: /products
weight: 10
- name: Leistungen
pageRef: /services
weight: 20
weight: 1
en:
languageCode: en-US
languageName: English
menus:
main:
- name: Products
pageRef: /products
weight: 10
- name: Services
pageRef: /services
weight: 20
weight: 2
[languages]
[languages.de]
languageCode = 'de-DE'
languageName = 'Deutsch'
weight = 1
[languages.de.menus]
[[languages.de.menus.main]]
name = 'Produkte'
pageRef = '/products'
weight = 10
[[languages.de.menus.main]]
name = 'Leistungen'
pageRef = '/services'
weight = 20
[languages.en]
languageCode = 'en-US'
languageName = 'English'
weight = 2
[languages.en.menus]
[[languages.en.menus.main]]
name = 'Products'
pageRef = '/products'
weight = 10
[[languages.en.menus.main]]
name = 'Services'
pageRef = '/services'
weight = 20
{
"languages": {
"de": {
"languageCode": "de-DE",
"languageName": "Deutsch",
"menus": {
"main": [
{
"name": "Produkte",
"pageRef": "/products",
"weight": 10
},
{
"name": "Leistungen",
"pageRef": "/services",
"weight": 20
}
]
},
"weight": 1
},
"en": {
"languageCode": "en-US",
"languageName": "English",
"menus": {
"main": [
{
"name": "Products",
"pageRef": "/products",
"weight": 10
},
{
"name": "Services",
"pageRef": "/services",
"weight": 20
}
]
},
"weight": 2
}
}
}
方法 2 – 使用配置目录
对于更复杂的菜单结构,请创建一个配置目录,并将菜单条目拆分为多个文件,每个文件对应一种语言。例如:
config/
└── _default/
├── menus.de.toml
├── menus.en.toml
└── hugo.toml
使用翻译表
当渲染菜单中每个条目的文本时,示例菜单模板会执行以下操作
{{ or (T .Identifier) .Name | safeHTML }}
它使用菜单条目的 identifier
查询当前语言的翻译表,并返回翻译后的字符串。如果翻译表不存在,或者翻译表中不存在 identifier
键,则会回退到 name
。
identifier
取决于您如何定义菜单条目
- 如果您使用节页面菜单自动定义菜单条目,则
identifier
是页面的.Section
。 - 如果您在站点配置中或在 front matter 中定义菜单条目,请将
identifier
属性设置为所需的值。
例如,如果您在站点配置中定义菜单条目
menus:
main:
- identifier: products
name: Products
pageRef: /products
weight: 10
- identifier: services
name: Services
pageRef: /services
weight: 20
[menus]
[[menus.main]]
identifier = 'products'
name = 'Products'
pageRef = '/products'
weight = 10
[[menus.main]]
identifier = 'services'
name = 'Services'
pageRef = '/services'
weight = 20
{
"menus": {
"main": [
{
"identifier": "products",
"name": "Products",
"pageRef": "/products",
"weight": 10
},
{
"identifier": "services",
"name": "Services",
"pageRef": "/services",
"weight": 20
}
]
}
}
在翻译表中创建相应的条目
products: Produkte
services: Leistungen
products = 'Produkte'
services = 'Leistungen'
{
"products": "Produkte",
"services": "Leistungen"
}
缺少翻译
如果某个字符串没有当前语言的翻译,Hugo 将使用默认语言的值。如果未设置默认值,则会显示空字符串。
在翻译 Hugo 网站时,有一个缺少翻译的可视指示器会很方便。enableMissingTranslationPlaceholders
配置选项将用占位符 [i18n] identifier
标记所有未翻译的字符串,其中 identifier
是缺少翻译的 ID。
对于从其他语言合并内容(即缺少内容翻译),请参阅 lang.Merge。
要跟踪缺少翻译的字符串,请使用 --printI18nWarnings
标志运行 Hugo
hugo --printI18nWarnings | grep i18n
i18n|MISSING_TRANSLATION|en|wordCount
多语言主题支持
为了在您的主题中支持多语言模式,必须考虑模板中的 URL。如果有多种语言,则 URL 必须满足以下条件
- 来自内置的
.Permalink
或.RelPermalink
- 使用
relLangURL
或absLangURL
模板函数构造,或者以{{ .LanguagePrefix }}
为前缀
如果定义了多种语言,LanguagePrefix
方法将返回 /en
(或当前语言)。如果未启用,它将是一个空字符串(因此对于单语言 Hugo 网站无害)。
使用 hugo new content
生成多语言内容
如果您在同一目录中组织带有翻译的内容
hugo new content post/test.en.md
hugo new content post/test.de.md
如果您在不同的目录中组织带有翻译的内容
hugo new content content/en/post/test.md
hugo new content content/de/post/test.md