1 files changed, 139 insertions, 19 deletions
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
+```