多语言模式

在站点配置文件的languages部分中定义可用的语言。

另请参阅[Hugo多语言第1部分：内容翻译]。

配置语言

这是默认的语言配置：

hugo.

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
      }
   }
}

以下是多语言项目的站点配置示例。如果在languages对象中未定义的键，则会回退到站点配置的全局值。

hugo.

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
en-gb
pt-br

defaultContentLanguageInSubdir: (bool) 如果为true，Hugo将在与defaultContentLanguage匹配的子目录中渲染默认语言站点。默认值是false。
contentDir: (string) 此语言的内容目录。如果使用通过文件名翻译，则省略该值。
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中的更改

在Hugo v0.112.0中，我们合并了所有配置选项，并改进了语言及其参数与主要配置的合并方式。但在对外部Hugo站点进行测试时，我们收到了一些错误报告，并且撤销了其中一些更改，转而使用不推荐的警告：

site.Language.Params已被弃用。直接使用site.Params。
在顶级语言配置中添加自定义参数已被弃用。在languages.xx.params内定义自定义参数。参见下面的示例中的color。

hugo.

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对象中禁用语言：

hugo.

languages:
  es:
    disabled: true

[languages]
  [languages.es]
    disabled = true

{
   "languages": {
      "es": {
         "disabled": true
      }
   }
}

在站点配置的根目录中禁用一个或多个语言：

hugo.

disableLanguages:
- es
- fr

disableLanguages = ['es', 'fr']

{
   "disableLanguages": [
      "es",
      "fr"
   ]
}

使用环境变量禁用一个或多个语言：

HUGO_DISABLELANGUAGES="es fr" hugo

请注意，无法禁用默认内容语言。

配置多语言多主机

从Hugo 0.31开始，我们支持多主机配置中的多语言。有关详细信息，请参阅此问题。

这意味着您现在可以为每种语言配置一个独立的baseURL：

示例：

hugo.

languages:
  en:
    baseURL: https://example.org/
    languageName: English
    title: In English
    weight: 2
  fr:
    baseURL: https://example.fr
    languageName: Français
    title: En Français
    weight: 1

[languages]
  [languages.en]
    baseURL = 'https://example.org/'
    languageName = 'English'
    title = 'In English'
    weight = 2
  [languages.fr]
    baseURL = 'https://example.fr'
    languageName = 'Français'
    title = 'En Français'
    weight = 1

{
   "languages": {
      "en": {
         "baseURL": "https://example.org/",
         "languageName": "English",
         "title": "In English",
         "weight": 2
      },
      "fr": {
         "baseURL": "https://example.fr",
         "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)
Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1)
Press Ctrl+C to stop

实时重新加载和在服务器之间使用--navigateToChanged参数导航功能都会按预期工作。

翻译内容

可以使用两种方法来管理内容翻译。两种方法都可以确保每个页面被分配了一种语言，并与其对应的其他语言版本链接在一起。

通过文件名翻译

考虑以下示例：

/content/about.en.md
/content/about.fr.md

第一个文件被分配了英文语言，并与第二个文件链接在一起。第二个文件被分配了法文语言，并与第一个文件链接在一起。

它们的语言是根据作为文件名后缀添加的语言代码进行__分配__的。

如果文件没有语言代码，它将被分配为默认语言。

通过内容目录翻译

该系统为每种语言使用不同的内容目录。使用contentDir参数设置每种语言的内容目录。

hugo.

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

第一个文件被分配了英文语言，并与第二个文件链接在一起。第二个文件被分配了法文语言，并与第一个文件链接在一起。

它们的语言是根据它们所__放置__的内容目录来__分配__的。

只要相对于其语言内容目录，它们具有相同的路径和基名称，这些内容片段就会作为翻译页面之间的__链接__。

跳过默认链接

只要页面在前面的元数据中设置了相同的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或url来本地化
对于部分页面，通过在元数据中设置url来本地化

例如，法文翻译可以有自己本地化的slug。

content/about.fr.md

---
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的顺序在捆绑中找到的第一个文件。

参考已翻译内容

要创建链接到已翻译内容的列表，请使用以下模板或类似模板：

layouts/partials/i18nlist.html

{{ if .IsTranslated }}
<h4>{{ i18n "translations" }}</h4>
<ul>
  {{ range .Translations }}
  <li>
    <a href="{{ .Permalink }}">{{ .Lang }}: {{ .Title }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
  </li>
  {{ end }}
</ul>
{{ end }}

上述模板可以放在模板中的任意位置（例如单个内容页面模板或首页模板中），如果某个页面没有翻译，则不会打印任何内容。

以上模板还使用了下一节中描述的[i18n函数][i18func]。

列出所有可用语言

在Page上使用.AllTranslations可列出所有翻译，包括页面本身。在主页上，它可用于构建语言导航：

layouts/partials/allLanguages.html

<ul>
{{ range $.Site.Home.AllTranslations }}
<li><a href="{{ .Permalink }}">{{ .Language.LanguageName }}</a></li>
{{ end }}
</ul>

多语言模式

配置语言

Hugo 0.112.0中的更改

禁用语言

配置多语言多主机

翻译内容

通过文件名翻译

通过内容目录翻译

跳过默认链接

本地化永久链接

页面捆绑

参考已翻译内容

列出所有可用语言

See also

Last updated: November 23, 2023: first release (332dc4cd7)