Translate.md - hugo - [fork] hugo port for 9front
HTML git clone https://git.drkhsh.at/hugo.git
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
Translate.md (6802B)
---
1 ---
2 title: lang.Translate
3 description: Translates a string using the translation tables in the i18n directory.
4 categories: []
5 keywords: []
6 params:
7 functions_and_methods:
8 aliases: [T, i18n]
9 returnType: string
10 signatures: ['lang.Translate KEY [CONTEXT]']
11 aliases: [/functions/i18n]
12 ---
13
14 The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language.
15
16 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`].
17
18 If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string.
19
20 > [!note]
21 > To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site.
22 >
23 > To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`] to `true` in your site configuration.
24
25 ## Translation tables
26
27 Create translation tables in the `i18n` directory, naming each file according to [RFC 5646]. Translation tables may be JSON, TOML, or YAML. For example:
28
29 ```text
30 i18n/en.toml
31 i18n/en-US.toml
32 ```
33
34 The base name must match the [language key] as defined in your site configuration.
35
36 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:
37
38 ```text
39 i18n/art-x-hugolang.toml
40 i18n/hugolang.toml
41 ```
42
43 > [!note]
44 > Private use subtags must not exceed 8 alphanumeric characters.
45
46 ## Simple translations
47
48 Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
49
50 ```text
51 i18n/
52 ├── en.toml
53 └── pl.toml
54 ```
55
56 The English translation table:
57
58 {{< code-toggle file=i18n/en >}}
59 privacy = 'privacy'
60 security = 'security'
61 {{< /code-toggle >}}
62
63 The Polish translation table:
64
65 {{< code-toggle file=i18n/pl >}}
66 privacy = 'prywatność'
67 security = 'bezpieczeństwo'
68 {{< /code-toggle >}}
69
70 > [!note]
71 > The examples below use the `T` alias for brevity.
72
73 When viewing the English language site:
74
75 ```go-html-template
76 {{ T "privacy" }} → privacy
77 {{ T "security" }} → security
78 ````
79
80 When viewing the Polish language site:
81
82 ```go-html-template
83 {{ T "privacy" }} → prywatność
84 {{ T "security" }} → bezpieczeństwo
85 ```
86
87 ## Translations with pluralization
88
89 Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
90
91 ```text
92 i18n/
93 ├── en.toml
94 └── pl.toml
95 ```
96
97 The Unicode [CLDR Plural Rules chart] describes the pluralization categories for each language.
98
99 The English translation table:
100
101 {{< code-toggle file=i18n/en >}}
102 [day]
103 one = 'day'
104 other = 'days'
105
106 [day_with_count]
107 one = '{{ . }} day'
108 other = '{{ . }} days'
109 {{< /code-toggle >}}
110
111 The Polish translation table:
112
113 {{< code-toggle file=i18n/pl >}}
114 [day]
115 one = 'miesiąc'
116 few = 'miesiące'
117 many = 'miesięcy'
118 other = 'miesiąca'
119
120 [day_with_count]
121 one = '{{ . }} miesiąc'
122 few = '{{ . }} miesiące'
123 many = '{{ . }} miesięcy'
124 other = '{{ . }} miesiąca'
125 {{< /code-toggle >}}
126
127 > [!note]
128 > The examples below use the `T` alias for brevity.
129
130 When viewing the English language site:
131
132 ```go-html-template
133 {{ T "day" 0 }} → days
134 {{ T "day" 1 }} → day
135 {{ T "day" 2 }} → days
136 {{ T "day" 5 }} → days
137
138 {{ T "day_with_count" 0 }} → 0 days
139 {{ T "day_with_count" 1 }} → 1 day
140 {{ T "day_with_count" 2 }} → 2 days
141 {{ T "day_with_count" 5 }} → 5 days
142 ````
143
144 When viewing the Polish language site:
145
146 ```go-html-template
147 {{ T "day" 0 }} → miesięcy
148 {{ T "day" 1 }} → miesiąc
149 {{ T "day" 2 }} → miesiące
150 {{ T "day" 5 }} → miesięcy
151
152 {{ T "day_with_count" 0 }} → 0 miesięcy
153 {{ T "day_with_count" 1 }} → 1 miesiąc
154 {{ T "day_with_count" 2 }} → 2 miesiące
155 {{ T "day_with_count" 5 }} → 5 miesięcy
156 ```
157
158 In the pluralization examples above, we passed an integer in context (the second argument). You can also pass a map in context, providing a `count` key to control pluralization.
159
160 Translation table:
161
162 {{< code-toggle file=i18n/en >}}
163 [age]
164 one = '{{ .name }} is {{ .count }} year old.'
165 other = '{{ .name }} is {{ .count }} years old.'
166 {{< /code-toggle >}}
167
168 Template code:
169
170 ```go-html-template
171 {{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old.
172 {{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old.
173 ```
174
175 > [!note]
176 > Translation tables may contain both simple translations and translations with pluralization.
177
178 ## Reserved keys
179
180 Hugo uses the [go-i18n] package to look up values in translation tables. This package reserves the following keys for internal use:
181
182 id
183 : (`string`) Uniquely identifies the message.
184
185 description
186 : (`string`) Describes the message to give additional context to translators that may be relevant for translation.
187
188 hash
189 : (`string`) Uniquely identifies the content of the message that this message was translated from.
190
191 leftdelim
192 : (`string`) The left Go template delimiter.
193
194 rightdelim
195 : (`string`) The right Go template delimiter.
196
197 zero
198 : (`string`) The content of the message for the [CLDR] plural form "zero".
199
200 one
201 : (`string`) The content of the message for the [CLDR] plural form "one".
202
203 two
204 : (`string`) The content of the message for the [CLDR] plural form "two".
205
206 few
207 : (`string`) The content of the message for the [CLDR] plural form "few".
208
209 many
210 : (`string`) The content of the message for the [CLDR] plural form "many".
211
212 other
213 : (`string`) The content of the message for the [CLDR] plural form "other".
214
215 If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example:
216
217 {{< code-toggle file=i18n/es >}}
218 _description = 'descripción'
219 _few = 'pocos'
220 _many = 'muchos'
221 _one = 'uno'
222 _other = 'otro'
223 _two = 'dos'
224 _zero = 'cero'
225 {{< /code-toggle >}}
226
227 Then in your templates:
228
229 ```go-html-template
230 {{ T "_description" }} → descripción
231 {{ T "_few" }} → pocos
232 {{ T "_many" }} → muchos
233 {{ T "_one" }} → uno
234 {{ T "_two" }} → dos
235 {{ T "_zero" }} → cero
236 {{ T "_other" }} → otro
237 ```
238
239 [`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
240 [`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders
241 [CLDR]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html
242 [CLDR Plural Rules chart]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html
243 [go-i18n]: https://github.com/nicksnyder/go-i18n
244 [language key]: /configuration/languages/#language-keys
245 [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
246 [RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7