多语言模式

配置语言

这是默认的语言配置

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）此语言的 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。

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

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

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

通过具有相同的**路径和基础文件名**，这些内容片段被**链接**在一起，作为翻译页面。

通过内容目录翻译

此系统为每种语言使用不同的内容目录。每种语言的 content 目录都使用 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

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

它们的语言是根据它们**放置**的 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 或 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="{{ .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
      }
   }
}

日期

使用此前端元数据

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 – 使用单个配置文件

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

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` 生成多语言内容

另请参阅

最后更新时间：2025 年 1 月 16 日：将目录名、文件名和文件路径格式化为代码 (8051ff818)

配置语言

Hugo 0.112.0 中的更改

禁用语言

配置多语言多主机

翻译您的内容

通过文件名翻译

通过内容目录翻译

绕过默认链接

本地化永久链接

页面包

引用翻译内容

列出所有可用的语言

字符串翻译

本地化

日期

货币

数字

百分比

菜单

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

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

方法 2 – 使用配置目录

使用翻译表

缺少翻译

多语言主题支持

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

另请参阅

最后更新时间：2025 年 1 月 16 日：将目录名、文件名和文件路径格式化为代码 (8051ff818)

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