From 2658a71e1b6fe24a8b754a62ce0398a09d270d86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Mon, 19 Feb 2024 18:59:28 +0100 Subject: [PATCH] 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 --- .../en/content-management/build-options.md | 4 +- content/en/functions/cast/ToInt.md | 4 +- content/en/functions/crypto/FNV32a.md | 2 + content/en/functions/lang/Translate.md | 158 +++++++++++++++--- content/en/functions/resources/GetRemote.md | 2 +- content/en/templates/data-templates.md | 2 +- content/en/templates/pagination.md | 2 +- content/en/templates/partials.md | 4 +- 8 files changed, 150 insertions(+), 28 deletions(-) diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md index bc9d7ff49..e8b3354bf 100644 --- a/content/en/content-management/build-options.md +++ b/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/content/en/functions/cast/ToInt.md b/content/en/functions/cast/ToInt.md index f82f029d5..c4bb10268 100644 --- a/content/en/functions/cast/ToInt.md +++ b/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/content/en/functions/crypto/FNV32a.md b/content/en/functions/crypto/FNV32a.md index eda303e62..c1e04183d 100644 --- a/content/en/functions/crypto/FNV32a.md +++ b/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/content/en/functions/lang/Translate.md b/content/en/functions/lang/Translate.md index 3366d7751..8c1b8f3f4 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: -- 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 +``` diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md index e596b2ab6..4a6540572 100644 --- a/content/en/functions/resources/GetRemote.md +++ b/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/content/en/templates/data-templates.md b/content/en/templates/data-templates.md index b862f727e..435bd70b2 100644 --- a/content/en/templates/data-templates.md +++ b/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 -
Short Description of {{ .Site.Data.User0123.Name }}:

{{ index .Site.Data.User0123 "Short Description" | markdownify }}

+
Short Description of {{ .Site.Data.user0123.Name }}:

{{ index .Site.Data.user0123 "Short Description" | markdownify }}

``` Note the use of the [`markdownify`] function. This will send the description through the Markdown rendering engine. diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md index 0854a6844..70a9df4cf 100644 --- a/content/en/templates/pagination.md +++ b/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/content/en/templates/partials.md b/content/en/templates/partials.md index 35ba2ee9e..afbad1a6c 100644 --- a/content/en/templates/partials.md +++ b/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/*.html` -2. `themes//layouts/partials/*.html` +1. `layouts/partials/.html` +2. `themes//layouts/partials/.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].