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:
Bjørn Erik Pedersen 2024-02-19 18:59:28 +01:00
parent 6efb279bfa
commit 2658a71e1b
8 changed files with 150 additions and 28 deletions

View file

@ -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'

View file

@ -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 %}}

View file

@ -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

View file

@ -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
```

View file

@ -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

View file

@ -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.

View file

@ -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`:

View file

@ -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].