Merge commit '2658a71e1b6fe24a8b754a62ce0398a09d270d86'

8 files changed, 150 insertions, 28 deletions

diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md
index bc9d7ff49..e8b3354bf 100644
--- a/docs/content/en/content-management/build-options.md
+++ b/docs/content/en/content-management/build-options.md
@@ -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'
diff --git a/docs/content/en/functions/cast/ToInt.md b/docs/content/en/functions/cast/ToInt.md
index f82f029d5..c4bb10268 100644
--- a/docs/content/en/functions/cast/ToInt.md
+++ b/docs/content/en/functions/cast/ToInt.md
@@ -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 %}}
diff --git a/docs/content/en/functions/crypto/FNV32a.md b/docs/content/en/functions/crypto/FNV32a.md
index eda303e62..c1e04183d 100644
--- a/docs/content/en/functions/crypto/FNV32a.md
+++ b/docs/content/en/functions/crypto/FNV32a.md
@@ -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
diff --git a/docs/content/en/functions/lang/Translate.md b/docs/content/en/functions/lang/Translate.md
index 3366d7751..8c1b8f3f4 100644
--- a/docs/content/en/functions/lang/Translate.md
+++ b/docs/content/en/functions/lang/Translate.md
@@ -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:
+
+{{< code-toggle file=i18n/en >}}
+privacy = 'privacy'
+security = 'security'
+{{< /code-toggle >}}
 
-- Simple translations
-- Translations with pluralization
+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
+```
diff --git a/docs/content/en/functions/resources/GetRemote.md b/docs/content/en/functions/resources/GetRemote.md
index e596b2ab6..4a6540572 100644
--- a/docs/content/en/functions/resources/GetRemote.md
+++ b/docs/content/en/functions/resources/GetRemote.md
@@ -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
diff --git a/docs/content/en/templates/data-templates.md b/docs/content/en/templates/data-templates.md
index b862f727e..435bd70b2 100644
--- a/docs/content/en/templates/data-templates.md
+++ b/docs/content/en/templates/data-templates.md
@@ -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.
diff --git a/docs/content/en/templates/pagination.md b/docs/content/en/templates/pagination.md
index 0854a6844..70a9df4cf 100644
--- a/docs/content/en/templates/pagination.md
+++ b/docs/content/en/templates/pagination.md
@@ -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`:
diff --git a/docs/content/en/templates/partials.md b/docs/content/en/templates/partials.md
index 35ba2ee9e..afbad1a6c 100644
--- a/docs/content/en/templates/partials.md
+++ b/docs/content/en/templates/partials.md
@@ -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].