mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-20 21:31:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '98293eaa1570b5aff4452021c8b6d6c8560b3f06'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2018-07-06 17:53:17 +02:00
parent 2b8d907ab7 98293eaa15
commit 0efd374805
26 changed files with 270 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
docs/content/en/content-management/multilingual.md
View File

@@ -35,14 +35,13 @@ help = "Help"
title = "My blog"
weight = 1
[languages.en.params]
linkedin = "english-link"
linkedin = "https://linkedin.com/whoever"
[languages.fr]
copyright = "Tout est à moi"
title = "Mon blog"
title = "Mon blogue"
weight = 2
[languages.fr.params]
linkedin = "lien-francais"
linkedin = "https://linkedin.com/fr/whoever"
[languages.fr.params.navigation]
help = "Aide"
{{< /code-toggle >}}
@@ -55,11 +54,13 @@ and taxonomy pages will be rendered below `/` in English (your default content l
When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation.
If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true`.
`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`.
If the default language needs to be rendererd below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`.
Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc.
## Disable a Language
### Disable a Language
You can disable one or more languages. This can be useful when working on a new translation.
@@ -81,7 +82,7 @@ HUGO_DISABLELANGUAGES=" " hugo server
```
## Configure Multilingual Multihost
### 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.
@@ -94,11 +95,11 @@ Example:
{{< code-toggle file="config" >}}
[languages]
[languages.no]
baseURL = "https://example.no"
languageName = "Norsk"
[languages.fr]
baseURL = "https://example.fr"
languageName = "Français"
weight = 1
title = "På norsk"
title = "En Français"
[languages.en]
baseURL = "https://example.com"
@@ -127,7 +128,7 @@ Press Ctrl+C to stop
Live reload and `--navigateToChanged` between the servers work as expected.
## Taxonomies and Blackfriday
### Taxonomies and Blackfriday
Taxonomies and [Blackfriday configuration][config] can also be set per language:
@@ -156,40 +157,113 @@ plaque = "plaques"
## Translate Your Content
Translated articles are identified by the name of the content file.
There are two ways to manage your content translation, both ensures each page is assigned a language and linked to its translations.
### Examples of Translated Articles
### Translation by filename
Considering the following example:
1. `/content/about.en.md`
2. `/content/about.fr.md`
In this example, the `about.md` will be assigned the configured `defaultContentLanguage`.
The first file is assigned the english language and linked to the second.
The second file is assigned the french language and linked to the first.
1. `/content/about.md`
2. `/content/about.fr.md`
Their language is __assigned__ according to the language code added as __suffix to the filename__.
This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`.
By having the same **path and base filename**, the content pieces are __linked__ together as translated pages.
{{< note >}}
By having the same **directory and base filename**, the content pieces are linked together as translated pieces.
If a file is missing any language code, it will be assigned the default language.
You can also set the key used to link the translations explicitly in front matter:
{{</ note >}}
### Translation by content directory
This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param.
{{< code-toggle file="config" >}}
languages:
en:
weight: 10
languageName: "English"
contentDir: "content/english"
nn:
weight: 20
languageName: "Français"
contentDir: "content/french"
{{< /code-toggle >}}
The value of `contentDir` can be any valid path, even absolute path references. The only restriction is that the content directories cannot overlap.
Considering the following example in conjunction with the configuration above:
1. `/content/english/about.md`
2. `/content/french/about.md`
The first file is assigned the english language and is linked to the second.
<br>The second file is assigned the french language and is linked to the first.
Their language is __assigned__ according to the content directory they are __placed__ in.
By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages.
### Bypassing default linking.
Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location.
Considering the following example:
1. `/content/about-us.en.md`
2. `/content/om.nn.md`
3. `/content/presentation/a-propos.fr.md`
```yaml
translationKey: "my-story"
# set in all three pages
translationKey: "about"
```
If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows:
By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages.
```yaml
### Localizing permalinks
Because paths and filenames are used to handle linking, all translated pages, except for the language part, will be sharing the same url.
To localize the URLs, the [`slug`]({{< ref "content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file.
For example, a french translation (`content/about.fr.md`) can have its own localized slug.
{{< code-toggle >}}
Title: A Propos
slug: "a-propos"
{{< /code-toggle >}}
```
At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages.
At render, Hugo will build both `/about/` and `fr/a-propos/` while maintaning their translation linking.
{{% note %}}
If using `url`, remember to include the language part as well: `fr/compagnie/a-propos/`.
{{%/ note %}}
For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/).
### Page Bundles
## Link to Translated Content
To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (markdown files, html files etc...).
Therefore, from within a template, the page will have access to the files from all linked pages' bundles.
If, across the linked bundles, two or more files share the same basenname, only one will be included and chosen as follows:
* File from current language Bundle, if present.
* First file found across bundles by order of language `Weight`.
{{% note %}}
Page Bundle's resources follow the same language assignement logic as content files, be it by filename (`image.jpg`, `image.fr.jpg`) or by directory (`english/about/header.jpg`, `french/about/header.jpg`).
{{%/ note %}}
## Reference the Translated Content
To create a list of links to translated content, use a template similar to the following:
@@ -210,7 +284,7 @@ The above can be put in a `partial` (i.e., inside `layouts/partials/`) and inclu
The above also uses the [`i18n` function][i18func] described in the next section.
## List All Available Languages
### List All Available Languages
`.AllTranslations` on a `Page` can be used to list all translations, including itself. Called on the home page it can be used to build a language navigator:

5
docs/content/en/content-management/shortcodes.md
View File

@@ -374,6 +374,10 @@ Using the preceding `youtube` example (without `autoplay="true"`), the following
{{< youtube w7Ft2ymGmfc >}}
## Privacy Config
To learn how to configure your Hugo site to meet the new EU privacy regulation, see [Hugo and the GDPR][].
## Create Custom Shortcodes
To learn more about creating custom shortcodes, see the [shortcode template documentation][].
@@ -382,6 +386,7 @@ To learn more about creating custom shortcodes, see the [shortcode template docu
[contentmanagementsection]: /content-management/formats/
[examplegist]: https://gist.github.com/spf13/7896402
[figureelement]: http://html5doctor.com/the-figure-figcaption-elements/ "An article from HTML5 doctor discussing the fig and figcaption elements."
[Hugo and the GDPR]: /about/hugo-and-gdpr/
[Instagram]: https://www.instagram.com/
[pagevariables]: /variables/page/
[partials]: /templates/partials/

8
docs/content/en/content-management/syntax-highlighting.md
View File

@@ -72,7 +72,13 @@ pygmentsCodefences
: Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
pygmentsStyle
: The style of code highlighting. See https://help.farbox.com/pygments.html for a gallery. Note that this option is not relevant when `pygmentsUseClasses` is set.
: The style of code highlighting. Note that this option is not
relevant when `pygmentsUseClasses` is set.
Syntax highlighting galleries:
**Chroma** ([short snippets](https://xyproto.github.io/splash/docs/all.html),
[long snippets](https://xyproto.github.io/splash/docs/longer/all.html)),
[Pygments](https://help.farbox.com/pygments.html)
pygmentsUseClasses
: Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css).