多语言模式

配置语言

这是默认的语言配置：

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

在上面， en 是语言键。

语言键必须符合 RFC 5646 中描述的语法。例如：

en
en-US

RFC 5646 § 2.2.7 中定义的具有专用子标签的人工语言也受支持。省略语言键中的 art-x- 前缀。例如：

hugolang

这是一个多语言项目的站点配置示例。在 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-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 中的更改

New in v0.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.Language.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 支持多主机配置中的多种语言。这意味着您可以为每个 language 配置一个 baseURL 。

示例：

hugo.

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 参数设置。

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

第一个文件被分配英语，并链接到第二个文件。第二个文件被分配法语，并链接到第一个文件。

它们的语言根据它们__所在__的内容目录进行__分配__。

通过拥有相同的 路径和基本名 （相对于它们的语言内容目录），内容片段被__链接__在一起作为翻译页面。

跳过默认链接

任何在 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：

对于普通页面，在 front matter 中设置 slug 或 url
对于章节页面，在 front matter 中设置 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="{{ .RelPermalink }}">{{ .Language.Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
  </li>
  {{ end }}
</ul>
{{ end }}

以上内容可以放在 partial 中（即，在 layouts/partials/ 内），并包含在任何模板中。如果给定页面没有翻译，它将不会打印任何内容。

上面还使用了下一节中描述的 i18n 函数。

列出所有可用的语言

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

layouts/partials/allLanguages.html

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

字符串翻译

参见 lang.Translate 模板函数。

本地化

以下本地化示例假设您的网站主要语言为英语，并提供法语和德语翻译。

hugo.

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

渲染后的页面显示：

语言	值
英语	Wednesday, November 3, 2021
法语	mercredi 3 novembre 2021
德语	Mittwoch, 3. November 2021

详情请参见 time.Format 。

货币

使用此模板代码：

{{ 512.5032 | lang.FormatCurrency 2 "USD" }}

渲染后的页面显示：

语言	值
英语	$512.50
法语	512,50 $US
德语	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 - 使用单个配置文件

对于条目数量较少的简单菜单，请使用单个配置文件。例如：

hugo.

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

config/_default/menus.de.

main:
- name: Produkte
  pageRef: /products
  weight: 10
- name: Leistungen
  pageRef: /services
  weight: 20

[[main]]
  name = 'Produkte'
  pageRef = '/products'
  weight = 10
[[main]]
  name = 'Leistungen'
  pageRef = '/services'
  weight = 20

{
   "main": [
      {
         "name": "Produkte",
         "pageRef": "/products",
         "weight": 10
      },
      {
         "name": "Leistungen",
         "pageRef": "/services",
         "weight": 20
      }
   ]
}

config/_default/menus.en.

main:
- name: Products
  pageRef: /products
  weight: 10
- name: Services
  pageRef: /services
  weight: 20

[[main]]
  name = 'Products'
  pageRef = '/products'
  weight = 10
[[main]]
  name = 'Services'
  pageRef = '/services'
  weight = 20

{
   "main": [
      {
         "name": "Products",
         "pageRef": "/products",
         "weight": 10
      },
      {
         "name": "Services",
         "pageRef": "/services",
         "weight": 20
      }
   ]
}

使用翻译表

渲染出现在每个菜单条目中的文本时，示例菜单模板执行以下操作：

{{ or (T .Identifier) .Name | safeHTML }}

它使用菜单条目的 identifier 查询当前语言的翻译表，并返回翻译后的字符串。如果翻译表不存在，或者 identifier 键不存在于翻译表中，则它将回退到 name 。

identifier 取决于您如何定义菜单条目：

如果你使用章节页面菜单自动定义菜单条目，则 identifier 是页面的 .Section 。
如果你在站点配置中或在 front matter 中定义菜单条目，请将 identifier 属性设置为所需的值。

例如，如果您在站点配置中定义菜单条目：

hugo.

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

在翻译表中创建相应的条目：

i18n/de.

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

多语言模式

配置语言

Hugo 0.112.0 中的更改

禁用语言

配置多语言多主机

翻译您的内容

按文件名翻译

按内容目录翻译

跳过默认链接

本地化永久链接

页面捆绑包

引用翻译后的内容

列出所有可用的语言

字符串翻译

本地化

日期

货币

数字

百分比

菜单

创建特定于语言的菜单条目

方法 1 - 使用单个配置文件

方法 2 - 使用配置目录

使用翻译表

缺失的翻译

多语言主题支持

使用 `hugo new content` 生成多语言内容

See also

Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)

配置语言

Hugo 0.112.0 中的更改

禁用语言

配置多语言多主机

翻译您的内容

按文件名翻译

按内容目录翻译

跳过默认链接

本地化永久链接

页面捆绑包

引用翻译后的内容

列出所有可用的语言

字符串翻译

本地化

日期

货币

数字

百分比

菜单

创建特定于语言的菜单条目

方法 1 - 使用单个配置文件

方法 2 - 使用配置目录

使用翻译表

缺失的翻译

多语言主题支持

使用 hugo new content 生成多语言内容

See also

Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)

使用 `hugo new content` 生成多语言内容