diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 71adc214d..6f15899c8 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -19,55 +19,77 @@ Also See [Hugo Multilingual Part 1: Content translation]. ## Configure Languages -The following is an example of a site configuration for a multilingual Hugo project: +This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration. {{< code-toggle file="hugo" >}} -defaultContentLanguage = "en" -copyright = "Everything is mine" +defaultContentLanguage = 'de' +defaultContentLanguageInSubdir = true -[params] -[params.navigation] -help = "Help" - -[languages] -[languages.en] -title = "My blog" +[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] -linkedin = "https://linkedin.com/whoever" - -[languages.fr] -title = "Mon blogue" -weight = 2 -[languages.fr.params] -linkedin = "https://linkedin.com/fr/whoever" -[languages.fr.params.navigation] -help = "Aide" - -[languages.ar] -title = "مدونتي" -weight = 2 -languagedirection = "rtl" - -[languages.pt-pt] -title = "O meu blog" -weight = 3 +subtitle = 'Reference, Tutorials, and Explanations' {{< /code-toggle >}} -Anything not defined in a `languages` block will fall back to the global value for that key (e.g., `copyright` for the English `en` language). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set. +`defaultContentLanguage` +: (`string`) The project's default language tag as defined by [RFC 5646]. Must be lower case, and must match one of the defined language keys. Default is `en`. Examples: -With the configuration above, all content, sitemap, RSS feeds, pagination, -and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French. +- `en` +- `en-gb` +- `pt-br` -When working with front matter `Params` in [single page templates], omit the `params` in the key for the translation. +`defaultContentLanguageInSubdir` +: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`. -`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`. +`contentDir` +: (`string`) The content directory for this language. Omit if [translating by file name]. -If the default language needs to be rendered below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`. +`disabled` +: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`. -Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. +`languageCode` +: (`string`) The language tag as defined by [RFC 5646]. This value may include upper and lower case characters, hyphens or underscores, and does not affect localization or URLs. Hugo uses this value to populate the `language` element in the [built-in RSS template], and the `lang` attribute of the `html` element in the [built-in alias template]. Examples: -**Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `defaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344) +- `en` +- `en-GB` +- `pt-BR` + +`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. + +`languageName` +: (`string`) The language name, typically used when rendering a language switcher. + +`title` +: (`string`) The language title. When set, this overrides the site title for this language. + +`weight` +: (`int`) The language weight. When set to a non-zero value, this is the primary sort criteria for this language. + +[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir +[built-in RSS template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml +[built-in alias template]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 +[translating by file name]: #translation-by-filename ### Changes in Hugo 0.112.0 @@ -92,7 +114,7 @@ color = "blue" In the example above, all settings except `color` below `params` map to predefined configuration options in Hugo for the site and its language, and should be accessed via the documented accessors: -``` +```go-html-template {{ site.Title }} {{ site.LanguageCode }} {{ site.Params.color }} @@ -100,26 +122,27 @@ In the example above, all settings except `color` below `params` map to predefin ### Disable a Language -You can disable one or more languages. This can be useful when working on a new translation. +To disable a language within a `languages` object in your site configuration: -{{< code-toggle file="hugo" >}} -disableLanguages = ["fr", "ja"] +{{< code-toggle file="hugo" copy=false >}} +[languages.es] +disabled = true {{< /code-toggle >}} +To disable one or more languages in the root of your site configuration: + +{{< code-toggle file="hugo" copy=false >}} +disableLanguages = ["es", "fr"] +{{< /code-toggle >}} + +To disable one or more languages using an environment variable: + +```bash +HUGO_DISABLELANGUAGES="es fr" hugo +``` + Note that you cannot disable the default content language. -We kept this as a standalone setting to make it easier to set via [OS environment]: - -```bash -HUGO_DISABLELANGUAGES="fr ja" hugo -``` - -If you have already a list of disabled languages in `hugo.toml`, you can enable them in development like this: - -```bash -HUGO_DISABLELANGUAGES=" " hugo server -``` - ### Configure Multilingual Multihost From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details.