mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-07 20:30:36 -05:00
Squashed 'docs/' changes from a9584e3d1..8c46b304a
8c46b304a Correct description of build options > render > link f57932df1 Fix front matter example a7e5fea73 Clarify pagination restriction 3a7e665db Fix typos f60845249 List translation keys reserved by nicksnyder/go-i18n 94f2a3608 Fix typo 2da1198ac Update FNV32a.md: new-in 0.98.0 d9a4c66ae Fix typo data-templates.md 0d3c2e2c3 Update partials.md d7e9a0878 Update partials.md git-subtree-dir: docs git-subtree-split: 8c46b304a0679d4e2b6c923ed0363efdfdcf48c1
This commit is contained in:
parent
6efb279bfa
commit
2658a71e1b
8 changed files with 150 additions and 28 deletions
|
@ -50,7 +50,7 @@ render
|
|||
: Always render the page to disk. This is the default value.
|
||||
|
||||
- `link`
|
||||
: Do not render the page to disk, but include it in all page collections.
|
||||
: Do not render the page to disk, but assign `Permalink` and `RelPermalink` values.
|
||||
|
||||
- `never`
|
||||
: Never render the page to disk, and exclude it from all page collections.
|
||||
|
@ -245,7 +245,7 @@ content/
|
|||
|
||||
Set the build options in front matter:
|
||||
|
||||
{{< code-toggle file=content/books/_index.md >}}
|
||||
{{< code-toggle file=content/books/_index.md fm=true >}}
|
||||
title = 'Books'
|
||||
[_build]
|
||||
render = 'never'
|
||||
|
|
|
@ -8,7 +8,7 @@ action:
|
|||
- functions/cast/ToFloat
|
||||
- functions/cast/ToString
|
||||
returnType: int
|
||||
signatures: [cast/ToInt INPUT]
|
||||
signatures: [cast.ToInt INPUT]
|
||||
aliases: [/functions/int]
|
||||
---
|
||||
|
||||
|
@ -49,5 +49,5 @@ With a hexadecimal (base 16) input:
|
|||
{{% note %}}
|
||||
Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros:
|
||||
|
||||
`{{ strings/TrimLeft "0" "0011" | int }} → 11`
|
||||
`{{ strings.TrimLeft "0" "0011" | int }} → 11`
|
||||
{{% /note %}}
|
||||
|
|
|
@ -15,6 +15,8 @@ action:
|
|||
aliases: [/functions/crypto.fnv32a]
|
||||
---
|
||||
|
||||
{{< new-in 0.98.0 >}}
|
||||
|
||||
This function calculates the 32-bit [FNV1a hash](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV-1a_hash) of a given string according to the [specification](https://datatracker.ietf.org/doc/html/draft-eastlake-fnv-12):
|
||||
|
||||
```go-html-template
|
||||
|
|
|
@ -8,17 +8,18 @@ action:
|
|||
related: []
|
||||
returnType: string
|
||||
signatures: ['lang.Translate KEY [CONTEXT]']
|
||||
toc: true
|
||||
aliases: [/functions/i18n]
|
||||
---
|
||||
|
||||
The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language.
|
||||
The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language.
|
||||
|
||||
If the key is not found in the translation table for the current language, the `lang.Translate` function falls back to the translation table for the [`defaultContentLanguage`].
|
||||
|
||||
If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string.
|
||||
If the key is not found in the translation table for the current language, the `lang.Translate` function falls back to the translation table for the [`defaultContentLanguage`].
|
||||
|
||||
[`defaultContentLanguage`]: /getting-started/configuration/#defaultcontentlanguage
|
||||
|
||||
If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string.
|
||||
|
||||
{{% note %}}
|
||||
To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site.
|
||||
|
||||
|
@ -28,6 +29,31 @@ To render placeholders for missing and fallback translations, set
|
|||
[`enableMissingTranslationPlaceholders`]: /getting-started/configuration/#enablemissingtranslationplaceholders
|
||||
{{% /note %}}
|
||||
|
||||
## Translation tables
|
||||
|
||||
Create translation tables in the i18n directory, naming each file according to [RFC 5646]. Translation tables may be JSON, TOML, or YAML. For example:
|
||||
|
||||
```text
|
||||
i18n/en.toml
|
||||
i18n/en-US.toml
|
||||
```
|
||||
|
||||
The base name must match the language key as defined in your site configuration.
|
||||
|
||||
Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. You may omit the `art-x-` prefix for brevity. For example:
|
||||
|
||||
```text
|
||||
i18n/art-x-hugolang.toml
|
||||
i18n/hugolang.toml
|
||||
```
|
||||
|
||||
Private use subtags must not exceed 8 alphanumeric characters.
|
||||
|
||||
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
|
||||
[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
|
||||
|
||||
## Simple translations
|
||||
|
||||
Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
|
||||
|
||||
```text
|
||||
|
@ -36,10 +62,47 @@ i18n/
|
|||
└── pl.toml
|
||||
```
|
||||
|
||||
The translation tables can contain both:
|
||||
The English translation table:
|
||||
|
||||
- Simple translations
|
||||
- Translations with pluralization
|
||||
{{< code-toggle file=i18n/en >}}
|
||||
privacy = 'privacy'
|
||||
security = 'security'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The Polish translation table:
|
||||
|
||||
{{< code-toggle file=i18n/pl >}}
|
||||
privacy = 'prywatność'
|
||||
security = 'bezpieczeństwo'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{% note %}}
|
||||
The examples below use the `T` alias for brevity.
|
||||
{{% /note %}}
|
||||
|
||||
When viewing the English language site:
|
||||
|
||||
```go-html-template
|
||||
{{ T "privacy" }} → privacy
|
||||
{{ T "security" }} → security
|
||||
````
|
||||
|
||||
When viewing the Polish language site:
|
||||
|
||||
```go-html-template
|
||||
{{ T "privacy" }} → prywatność
|
||||
{{ T "security" }} → bezpieczeństwo
|
||||
```
|
||||
|
||||
## Translations with pluralization
|
||||
|
||||
Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
|
||||
|
||||
```text
|
||||
i18n/
|
||||
├── en.toml
|
||||
└── pl.toml
|
||||
```
|
||||
|
||||
The Unicode [CLDR Plural Rules chart] describes the pluralization categories for each language.
|
||||
|
||||
|
@ -48,9 +111,6 @@ The Unicode [CLDR Plural Rules chart] describes the pluralization categories for
|
|||
The English translation table:
|
||||
|
||||
{{< code-toggle file=i18n/en >}}
|
||||
privacy = 'privacy'
|
||||
security = 'security'
|
||||
|
||||
[day]
|
||||
one = 'day'
|
||||
other = 'days'
|
||||
|
@ -63,9 +123,6 @@ other = '{{ . }} days'
|
|||
The Polish translation table:
|
||||
|
||||
{{< code-toggle file=i18n/pl >}}
|
||||
privacy = 'prywatność'
|
||||
security = 'bezpieczeństwo'
|
||||
|
||||
[day]
|
||||
one = 'miesiąc'
|
||||
few = 'miesiące'
|
||||
|
@ -86,9 +143,6 @@ The examples below use the `T` alias for brevity.
|
|||
When viewing the English language site:
|
||||
|
||||
```go-html-template
|
||||
{{ T "privacy" }} → privacy
|
||||
{{ T "security" }} → security
|
||||
|
||||
{{ T "day" 0 }} → days
|
||||
{{ T "day" 1 }} → day
|
||||
{{ T "day" 2 }} → days
|
||||
|
@ -103,9 +157,6 @@ When viewing the English language site:
|
|||
When viewing the Polish language site:
|
||||
|
||||
```go-html-template
|
||||
{{ T "privacy" }} → prywatność
|
||||
{{ T "security" }} → bezpieczeństwo
|
||||
|
||||
{{ T "day" 0 }} → miesięcy
|
||||
{{ T "day" 1 }} → miesiąc
|
||||
{{ T "day" 2 }} → miesiące
|
||||
|
@ -133,3 +184,72 @@ Template code:
|
|||
{{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old.
|
||||
{{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old.
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Translation tables may contain both simple translations and translations with pluralization.
|
||||
{{% /note %}}
|
||||
|
||||
## Reserved keys
|
||||
|
||||
Hugo uses the [go-i18n] package to look up values in translation tables. This package reserves the following keys for internal use:
|
||||
|
||||
[go-i18n]: https://github.com/nicksnyder/go-i18n
|
||||
|
||||
id
|
||||
: (`string`) Uniquely identifies the message.
|
||||
|
||||
description
|
||||
: (`string`) Describes the message to give additional context to translators that may be relevant for translation.
|
||||
|
||||
hash
|
||||
: (`string`) Uniquely identifies the content of the message that this message was translated from.
|
||||
|
||||
leftdelim
|
||||
: (`string`) The left Go template delimiter.
|
||||
|
||||
rightdelim
|
||||
: (`string`) The right Go template delimiter.
|
||||
|
||||
zero
|
||||
: (`string`) The content of the message for the [CLDR] plural form "zero".
|
||||
|
||||
one
|
||||
: (`string`) The content of the message for the [CLDR] plural form "one".
|
||||
|
||||
two
|
||||
: (`string`) The content of the message for the [CLDR] plural form "two".
|
||||
|
||||
few
|
||||
: (`string`) The content of the message for the [CLDR] plural form "few".
|
||||
|
||||
many
|
||||
: (`string`) The content of the message for the [CLDR] plural form "many".
|
||||
|
||||
other
|
||||
: (`string`) The content of the message for the [CLDR] plural form "other".
|
||||
|
||||
[CLDR]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html
|
||||
|
||||
If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example:
|
||||
|
||||
{{< code-toggle file=i18n/es >}}
|
||||
_description = 'descripción'
|
||||
_few = 'pocos'
|
||||
_many = 'muchos'
|
||||
_one = 'uno'
|
||||
_other = 'otro'
|
||||
_two = 'dos'
|
||||
_zero = 'cero'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
Then in your templates:
|
||||
|
||||
```go-html-template
|
||||
{{ T "_description" }} → descripción
|
||||
{{ T "_few" }} → pocos
|
||||
{{ T "_many" }} → muchos
|
||||
{{ T "_one" }} → uno
|
||||
{{ T "_two" }} → dos
|
||||
{{ T "_zero" }} → cero
|
||||
{{ T "_other" }} → otro
|
||||
```
|
||||
|
|
|
@ -171,7 +171,7 @@ Override the cache key by setting a `key` in the options map. Use this approach
|
|||
```go-html-template
|
||||
{{ $url := "https://example.org/images/a.jpg" }}
|
||||
{{ $cacheKey := print $url (now.Format "2006-01-02") }}
|
||||
{{ $resource := resource.GetRemote $url (dict "key" $cacheKey) }}
|
||||
{{ $resource := resources.GetRemote $url (dict "key" $cacheKey) }}
|
||||
```
|
||||
|
||||
[configure file caches]: /getting-started/configuration/#configure-file-caches
|
||||
|
|
|
@ -127,7 +127,7 @@ Achievements:
|
|||
You can use the following code to render the `Short Description` in your layout:
|
||||
|
||||
```go-html-template
|
||||
<div>Short Description of {{ .Site.Data.User0123.Name }}: <p>{{ index .Site.Data.User0123 "Short Description" | markdownify }}</p></div>
|
||||
<div>Short Description of {{ .Site.Data.user0123.Name }}: <p>{{ index .Site.Data.user0123 "Short Description" | markdownify }}</p></div>
|
||||
```
|
||||
|
||||
Note the use of the [`markdownify`] function. This will send the description through the Markdown rendering engine.
|
||||
|
|
|
@ -31,7 +31,7 @@ Setting `paginate` to a positive value will split the list pages for the homepag
|
|||
## List paginator pages
|
||||
|
||||
{{% note %}}
|
||||
`.Paginator` is provided to help you build a pager menu. This feature is currently only supported on homepage and list pages (i.e., taxonomies and section lists).
|
||||
Paginate a page collection in list templates for these page kinds: `home`, `section`, `taxonomy`, or `term`. You cannot paginate a page collection in a template for the `page` page kind.
|
||||
{{% /note %}}
|
||||
|
||||
There are two ways to configure and use a `.Paginator`:
|
||||
|
|
|
@ -18,8 +18,8 @@ aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/]
|
|||
|
||||
Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order]. However, partials are simpler in that Hugo will only check in two places:
|
||||
|
||||
1. `layouts/partials/*<PARTIALNAME>.html`
|
||||
2. `themes/<THEME>/layouts/partials/*<PARTIALNAME>.html`
|
||||
1. `layouts/partials/<PARTIALNAME>.html`
|
||||
2. `themes/<THEME>/layouts/partials/<PARTIALNAME>.html`
|
||||
|
||||
This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize].
|
||||
|
||||
|
|
Loading…
Reference in a new issue