Internationalization (i18n)
This guide describes how to set up and use Doks in Multilingual mode.
Looking for an example?
Check out the Doks Multilingual example project and demo site.
Set up
Enable
In config/_default/params.toml, enable Multilinguage Mode:
# Doks (@thulite/doks-core)
[doks]
# Multilingual
multilingualMode = true # false (default) or true
showMissingLanguages = true # whether or not to show untranslated languages in the language menu; true (default) or falseSet languages
In ./config/_default/hugo.toml, set languages:
# Multilingual
defaultContentLanguage = "en"
disableLanguages = []
defaultContentLanguageInSubdir = falseSet language settings
In ./config/_default/languages.toml, set language settings (for each language):
[en]
contentDir = "content/en"
disabled = false
languageCode = 'en-US'
languageDirection = 'ltr'
languageName = 'English'
title = 'Project Documentation'
weight = 10
[en.params]
footer = 'Brought to you by <a class="text-muted" href="https://thulite.io/">Thulite</a>'
[de]
contentDir = "content/de"
disabled = false
languageCode = 'de-DE'
languageDirection = 'ltr'
languageName = 'Deutsch'
title = 'Projekt Dokumentation'
weight = 20
[de.params]
footer = 'Präsentiert von <a class="text-muted" href="https://thulite.io/">Thulite</a>'
[nl]
contentDir = "content/nl"
disabled = false
languageCode = 'nl-NL'
languageDirection = 'ltr'
languageName = 'Nederlands'
title = 'Projekt documentatie'
weight = 30
[nl.params]
footer = 'Aangeboden door <a class="text-muted" href="https://thulite.io/">Thulite</a>'Update mounts
In config/_default/module.toml update module mounts:
## content
[[mounts]]
source = "content/en"
target = "content"
lang = "en"
[[mounts]]
source = "content/de"
target = "content"
lang = "de"
[[mounts]]
source = "content/nl"
target = "content"
lang = "nl"Set menu entries
In config/_default/menus/menus.<ISO country code lowercase>.toml (so, e.g. in config/_default/menus/menus.en.toml), set menu entries (for each language).
Set translation strings
In i18n/<ISO country code lowercase>.toml (so, e.g. in i18n/en.toml), set translation strings (for each language).
FlexSearch
Copy node_modules/@thulite/doks-core/assets/js/flexsearch.js and paste as assets/js/flexsearch.<ISO country code lowercase>.js (for each language) — so, e.g assets/js/flexsearch.en.js.
Add content
In content.<ISO country code lowercase>/ (so, e.g. in content/en/), add content (for each language).
Build content
Inside your project directory, run the following command to start the development server:
Example output:
..
Start building sites …
hugo v0.134.2-1c74abd26070b0c12849550c974a9f3f1e7afb06+extended windows/amd64 BuildDate=2024-09-10T10:46:33Z VendorInfo=gohugoio
| EN | DE | NL
-------------------+----+----+-----
Pages | 30 | 27 | 27
Paginator pages | 0 | 0 | 0
Non-page files | 0 | 0 | 0
Static files | 13 | 13 | 13
Processed images | 4 | 0 | 0
Aliases | 5 | 4 | 4
Cleaned | 0 | 0 | 0
Built in 487 ms
Environment: "development"
Serving pages from disk
..Switch content
The language switch is part of the global navigation (available on all pages).
If the current page is available in the newly selected language, the corresponding page in the newly selected language is shown.
If the current page is not available in the newly selected language, the homepage of the newly selected language is shown.
Common issues
Changes not reflected
Clear cache, for example:
npx shx rm -rf public resources hugo_stats.json .hugo_build.lockAnd run development server:
Tips
Fill in missing translations
In config/_default/module.toml add for example the following module mounts (in addition to Update mounts ):
## content
### Fill in the gaps in DE content with EN content
[[mounts]]
source = "content/en"
target = "content"
lang = "de"
### Fill in the gaps in NL content with EN content
[[mounts]]
source = "content/en"
target = "content"
lang = "nl"