diff --git a/content/en/functions/lang/Translate.md b/content/en/functions/lang/Translate.md index 3366d7751e..8c1b8f3f41 100644 --- a/content/en/functions/lang/Translate.md +++ b/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 +```