多语言模式
配置语言
这是默认语言配置
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
是语言键。
这是一个多语言项目的站点配置示例。在 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
}
}
}
- 默认内容语言
- (
字符串
) 项目的默认语言键,符合RFC 5646中描述的语法。此值必须与已定义的语言键之一匹配。示例
en
en-GB
pt-BR
- 在子目录中使用默认内容语言
- (
布尔值
) 如果为true
,Hugo 会在与defaultContentLanguage
匹配的子目录中渲染默认语言站点。默认为false
。 - 内容目录
- (
字符串
) 此语言的内容目录。如果按文件名翻译,则省略。 - 禁用
- (
布尔值
) 如果为true
,Hugo 将不会渲染此语言的内容。默认为false
。 - 语言代码
- (
字符串
) 如RFC 5646中所述的语言标签。此值不会影响本地化或 URL。Hugo 使用此值填充内置 RSS 模板中的language
元素,以及内置别名模板中html
元素的lang
属性。示例
en
en-GB
pt-BR
- 语言方向
- (
字符串
) 语言方向,从左到右 (ltr
) 或从右到左 (rtl
)。在您的模板中使用此值与全局dir
HTML 属性一起使用。 - 语言名称
- (
字符串
) 语言名称,通常用于渲染语言切换器时。 - 标题
- (
字符串
) 此语言的站点标题(可选)。 - 权重
- (
整数
) 语言权重。当设置为非零值时,这是此语言的主要排序标准。
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.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
第一个文件被分配为英语,并链接到第二个文件。第二个文件被分配为法语,并链接到第一个文件。
它们的语言根据作为**文件名后缀**添加的语言代码进行**分配**。
通过具有相同的**路径和基本文件名**,内容片段被**链接**在一起作为翻译后的页面。
根据内容目录翻译
此系统为每种语言使用不同的内容目录。每种语言的内容目录使用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
第一个文件被分配为英语,并链接到第二个文件。第二个文件被分配为法语,并链接到第一个文件。
它们的语言根据它们所在的**内容目录**进行**分配**。
通过具有相同的**路径和基本名称**(相对于其语言内容目录),内容片段被**链接**在一起作为翻译后的页面。
绕过默认链接
任何在 front matter 中设置了相同translationKey
的页面都将链接为翻译后的页面,而不管基本名称或位置如何。
考虑以下示例
/content/about-us.en.md
/content/om.nn.md
/content/presentation/a-propos.fr.md
translationKey: about
translationKey = 'about'
{
"translationKey": "about"
}
通过在所有三个页面中将translationKey
front matter 参数设置为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
}
}
}
日期
使用此 front matter
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。
菜单
菜单条目的本地化取决于您如何定义它们
- 当您使用章节页面菜单自动定义菜单条目时,必须使用翻译表来本地化每个条目。
- 当您在front matter中定义菜单条目时,它们已根据 front matter 本身进行本地化。如果 front matter 值不足,请使用翻译表来本地化每个条目。
- 当您在站点配置中定义菜单条目时,必须在每个语言键下创建特定于语言的菜单条目。如果菜单条目的名称不足,请使用翻译表来本地化每个条目。
创建特定于语言的菜单条目
方法 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
。 - 如果您在 站点配置 或 前置 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