HUGO
News Docs Themes Community GitHub

Configure languages

Configure the languages in your multilingual site.

Base settings

Configure the following base settings within the site’s root configuration:

defaultContentLanguage: en
defaultContentLanguageInSubdir: false
disableDefaultLanguageRedirect: false
disableLanguages: []

defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = false
disableDefaultLanguageRedirect = false
disableLanguages = []

{
   "defaultContentLanguage": "en",
   "defaultContentLanguageInSubdir": false,
   "disableDefaultLanguageRedirect": false,
   "disableLanguages": []
}
defaultContentLanguage
(string) The project’s default language key, conforming to the syntax described in RFC 5646. This value must match one of the defined language keys. Default is en.
defaultContentLanguageInSubdir
(bool) Whether to publish the default language site to a subdirectory matching the defaultContentLanguage. Default is false.
disableDefaultLanguageRedirect
New in v0.140.0
(bool) Whether to disable generation of the alias redirect to the default language when DefaultContentLanguageInSubdir is true. Default is false.
disableLanguages
([]string]) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the disabled key under each language instead.

Language settings

Configure each language under the languages key:

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

In the above, en is the language key.

disabled
(bool) Whether to disable this language when building the site. Default is false.
languageCode
(string) The language tag as described in RFC 5646. This value does not affect localization or URLs. Hugo uses this value to populate:

Access this value from a template using the Language.LanguageCode method on a Site or Page object.

languageDirection
(string) The language direction, either left-to-right (ltr) or right-to-left (rtl). Use this value in your templates with the global dir HTML attribute. Access this value from a template using the Language.LanguageDirection method on a Site or Page object.
languageName
(string) The language name, typically used when rendering a language switcher. Access this value from a template using the Language.LanguageName method on a Site or Page object.
title
(string) The site title for this language. Access this value from a template using the Title method on a Site object.
weight
(int) The language weight. When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the Language.Weight method on a Site or Page object.

Localized settings

Some configuration settings can be defined separately for each language. For example:

languages:
  en:
    languageCode: en-US
    languageName: English
    pagination:
      path: page
    params:
      subtitle: Reference, Tutorials, and Explanations
    timeZone: America/New_York
    title: Project Documentation
    weight: 1

[languages]
  [languages.en]
    languageCode = 'en-US'
    languageName = 'English'
    timeZone = 'America/New_York'
    title = 'Project Documentation'
    weight = 1
    [languages.en.pagination]
      path = 'page'
    [languages.en.params]
      subtitle = 'Reference, Tutorials, and Explanations'

{
   "languages": {
      "en": {
         "languageCode": "en-US",
         "languageName": "English",
         "pagination": {
            "path": "page"
         },
         "params": {
            "subtitle": "Reference, Tutorials, and Explanations"
         },
         "timeZone": "America/New_York",
         "title": "Project Documentation",
         "weight": 1
      }
   }
}

The following configuration keys can be defined separately for each language:

baseURL buildDrafts buildExpired buildFuture canonifyURLs capitalizeListTitles contentDir copyright disableAliases disableHugoGeneratorInject disableKinds disableLiveReload disablePathToLower enableEmoji frontmatter hasCJKLanguage languageCode mainSections markup mediaTypes menus outputFormats outputs page pagination params permalinks pluralizeListTitles privacy refLinksErrorLevel refLinksNotFoundURL related relativeURLs removePathAccents renderSegments sectionPagesMenu security services sitemap staticDir summaryLength taxonomies timeZone title titleCaseStyle

Any key not defined in a languages object will fall back to the global value in the root of the site configuration.

Language keys

Language keys must conform to the syntax described in RFC 5646. For example:

defaultContentLanguage: de
languages:
  de:
    weight: 1
  en-US:
    weight: 2
  pt-BR:
    weight: 3

defaultContentLanguage = 'de'
[languages]
  [languages.de]
    weight = 1
  [languages.en-US]
    weight = 2
  [languages.pt-BR]
    weight = 3

{
   "defaultContentLanguage": "de",
   "languages": {
      "de": {
         "weight": 1
      },
      "en-US": {
         "weight": 2
      },
      "pt-BR": {
         "weight": 3
      }
   }
}

Artificial languages with private use subtags as defined in RFC 5646 § 2.2.7 are also supported. Omit the art-x- prefix from the language key. For example:

defaultContentLanguage: en
languages:
  en:
    weight: 1
  hugolang:
    weight: 2

defaultContentLanguage = 'en'
[languages]
  [languages.en]
    weight = 1
  [languages.hugolang]
    weight = 2

{
   "defaultContentLanguage": "en",
   "languages": {
      "en": {
         "weight": 1
      },
      "hugolang": {
         "weight": 2
      }
   }
}

Private use subtags must not exceed 8 alphanumeric characters.

Example

defaultContentLanguage: de
defaultContentLanguageInSubdir: true
disableDefaultLanguageRedirect: false
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
disableDefaultLanguageRedirect = false
[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,
   "disableDefaultLanguageRedirect": false,
   "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
      }
   }
}

In the example above, omit contentDir if translating by file name.

Multihost

Hugo supports multiple languages in a multihost configuration. This means you can configure a baseURL per language.

If you define a baseURL for one language, you must define a unique baseURL for all languages.

For example:

defaultContentLanguage: fr
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

defaultContentLanguage = 'fr'
[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

{
   "defaultContentLanguage": "fr",
   "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
      }
   }
}

With the above, Hugo publishes two sites, each with their own root:

public
├── en
└── fr
Last updated: March 5, 2025 : content: Consolidate configuration documentation (b6cae5cbc)
Improve this page