Improve multilingual config example and descriptions

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"
+defaultContentLanguage = 'de'
-copyright = "Everything is mine"
+defaultContentLanguageInSubdir = true
 
-[params]
+[languages.de]
-[params.navigation]
+contentDir = 'content/de'
-help  = "Help"
+disabled = false
-
+languageCode = 'de-DE'
-[languages]
+languageDirection = 'ltr'
-[languages.en]
+languageName = 'Deutsch'
-title = "My blog"
+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"
+subtitle = 'Reference, Tutorials, and Explanations'
-
-[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
 {{< /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,
+- `en`
-and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French.
+- `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" >}}
+{{< code-toggle file="hugo" copy=false >}}
-disableLanguages = ["fr", "ja"]
+[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.