Hudocs uses Hugo’s native internationalization system to manage content and interface text in multiple languages. Any option or multilingual content structure supported by Hugo is also supported by Hudocs.

Language configuration #

Declare each language inside the [languages] block of your configuration file:

[languages]
  [languages.en]
    label = "English"
    weight = 1

  [languages.es]
    label = "Español"
    weight = 2
  • weight: determines the order of the languages. The language with the lowest value is used as the default language.
  • label: name displayed in the language selector in the header.

See the Hugo internationalization documentation for the available options.

Content translation #

Multilingual files #

Hudocs uses Hugo’s native multilingual system to associate translations of the same page. For example, you can use language suffixes in file names:

content/docs/latest/guides/
├── navigation.md        # English version
└── navigation.es.md     # Spanish version

Hugo automatically associates documents belonging to the same page. The language selector in the header links to the corresponding translation when available.

Translating section indexes #

Section titles, descriptions, and redirects can also be translated using language-specific _index files:

content/docs/latest/guides/
├── _index.md        # title: "Guides"
└── _index.es.md     # title: "Guías"

Interface localization #

Fixed theme text, such as search placeholders, copy notifications, pagination labels, and color mode names, is managed through TOML files in the i18n/ directory.

Customize or add languages #

To override existing translations or add another language:

  1. Create the translation directory #

    Create an i18n/ directory in the root of your project:

    my-project/
├── i18n/
│   └── fr.toml
└── hugo.toml

  2. Add the translations #

    Add the translated strings to i18n/fr.toml:

    [search]
other = "Rechercher"

[search_in_doc]
other = "Rechercher dans la documentation"

[copy]
other = "Copier"

  3. Register the language #

    Register the language under [languages.fr] in hugo.toml.

Hudocs generates a separate search index for each configured language. When searching from a localized version, the results correspond to the selected language:

/json/en.docs.latest.index.<hash>.json
/json/es.docs.latest.index.<hash>.json