You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 3909516
Browse filesBrowse the repository at this point in the historyBrowse files
Add parity test and translator guidance for language files (#15265)
Keys added to _language.yml did not reach the per-language files, and
nothing checked for it, so localized pages fell back to English for
those strings (#14822). Two files also used keys that no longer match
_language.yml. This adds a test that keeps the language files in step
with _language.yml, and translator comments that say which sense of
each key to use.
- tests/unit/language-parity.test.ts: fails when a language file has a
key missing from _language.yml, when a base language lacks a key that
is not in language-known-gaps.yml, when that list goes stale, or when
a value does not keep the {0} placeholders of the English value.
Region files are overlays on their base language, so they skip only
the missing-key check.
- lt and sv: rename the stale keys (search to search-label, and
callout-danger-title to callout-caution-title), keeping the existing
values. The Swedish file (#5000) used a key name that was already
gone when it was added.
- _language.yml: translator comments above each key missing from some
file: what the string is, where it shows, and which sense to use.
- src/resources/language/README.md and AGENTS.md: the full list of
language files and contributing guidance for translators, including
disclosure of AI help.
Related to #14822. Once #14203 lands, its Arabic file needs every key
translated or listed in language-known-gaps.yml.
Copy file name to clipboardExpand all lines: .claude/rules/rendering/localization.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,3 +7,5 @@ paths:
7
7
# Localization
8
8
9
9
For how localized strings flow from `_language.yml` through metadata merging into Pandoc templates and the crossref/authors/callouts Lua filters, see `llm-docs/localization-architecture.md`.
10
+
11
+
For editing `_language-*.yml` files, follow `src/resources/language/README.md` and `src/resources/language/AGENTS.md` (translator notes, placeholders, parity test).
Copy file name to clipboardExpand all lines: news/changelog-1.12.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,3 +20,4 @@ All changes included in 1.12:
20
20
## Other fixes and improvements
21
21
22
22
- ([#14822](https://github.com/quarto-dev/quarto-cli/issues/14822)): Translate the `tools-share`, `tools-download`, and `skip-to-content` language keys in Greek. (author: @sogav21)
23
+
- ([#14822](https://github.com/quarto-dev/quarto-cli/issues/14822)): The Lithuanian search label and the Swedish caution callout title no longer fall back to English.
- Read the translator comment above each key you translate in `_language.yml`. Some strings are screen-reader labels or use words in a specific sense.
7
+
- Keep the `{0}`-style placeholders exactly as they appear in the English value.
8
+
- Reuse the vocabulary and verb forms already in the target file.
9
+
- Region files (`de-CH`, `fr-CA`, `pt-BR`, `zh-TW`) are overlays: only add keys that differ from the base language.
10
+
- Run `unit/language-parity.test.ts` (see `.claude/rules/testing/overview.md`); an English key you cannot translate goes in `tests/unit/language-known-gaps.yml`.
|`_language-fr-CA.yml`| Canadian French (overlay) |
15
+
|`_language-ca.yml`| Catalan |
16
+
|`_language-zh.yml`| Chinese |
17
+
|`_language-cs.yml`| Czech |
18
+
|`_language-da.yml`| Danish |
19
+
|`_language-nl.yml`| Dutch |
20
+
|`_language-fi.yml`| Finnish |
21
+
|`_language-fr.yml`| French |
22
+
|`_language-de.yml`| German |
23
+
|`_language-el.yml`| Greek |
24
+
|`_language-he.yml`| Hebrew |
25
+
|`_language-is.yml`| Icelandic |
26
+
|`_language-id.yml`| Indonesian |
27
+
|`_language-it.yml`| Italian |
28
+
|`_language-ja.yml`| Japanese |
29
+
|`_language-ko.yml`| Korean |
30
+
|`_language-lt.yml`| Lithuanian |
31
+
|`_language-nb.yml`| Norwegian Bokmål |
32
+
|`_language-nn.yml`| Norwegian Nynorsk |
33
+
|`_language-pl.yml`| Polish |
34
+
|`_language-pt.yml`| Portuguese |
35
+
|`_language-ru.yml`| Russian |
36
+
|`_language-sr-Latn.yml`| Serbian (Latin script) |
37
+
|`_language-sk.yml`| Slovak |
38
+
|`_language-sl.yml`| Slovenian |
39
+
|`_language-es.yml`| Spanish |
40
+
|`_language-sv.yml`| Swedish |
41
+
|`_language-de-CH.yml`| Swiss German (overlay) |
42
+
|`_language-zh-TW.yml`| Traditional Chinese (Taiwan) (overlay) |
43
+
|`_language-tr.yml`| Turkish |
44
+
|`_language-ua.yml`| Ukrainian |
30
45
31
46
The use of these translations is triggered by the [`lang`](https://pandoc.org/MANUAL.html#language-variables) Pandoc metadata variable, which identifies the main language of the document using IETF language tags (following the [BCP 47](https://tools.ietf.org/html/bcp47) standard), such as `en` or `en-GB`. The [Language subtag lookup](https://r12a.github.io/app-subtags/) tool can look up or verify these tags.
32
47
@@ -41,10 +56,20 @@ lang: fr
41
56
42
57
## Contributing Localizations
43
58
44
-
We welcome contributions of additional languages! To contribute a localization:
59
+
We welcome translations for new languages and for missing strings in existing languages! To contribute a localization:
45
60
46
-
1.Make a copy of the `_language.yml` file with the appropriate IETF language tag appended to the filename (e.g. `_language-fr.yml`).
61
+
1.For a new language, make a copy of the `_language.yml` file with the appropriate IETF language tag appended to the filename (e.g. `_language-fr.yml`).
47
62
48
-
2. Translate the English strings therein to the target language.
63
+
2. Translate the English strings into the target language. Before translating a key, read its translator comment in `_language.yml`. Some strings are screen-reader labels or use words in a specific sense, as the comments explain.
49
64
50
-
3. Submit a [pull request](https://help.github.com/articles/using-pull-requests) with your new language translation.
65
+
3. Reuse the vocabulary and verb forms already used in your language file so the interface stays consistent.
66
+
67
+
4. Keep the `{0}`-style placeholders exactly as they appear in the English value.
68
+
69
+
5. Submit a [pull request](https://help.github.com/articles/using-pull-requests) with your translation.
70
+
71
+
A few more things to know:
72
+
73
+
-**Region files are overlays.**`de-CH`, `fr-CA`, `pt-BR` and `zh-TW` are read on top of `de`, `fr`, `pt` and `zh`, so they only need the keys that differ from their base language.
74
+
-**AI help is welcome.** Check the translation against the translator comments and existing strings in the language file, and mention in the pull request that you used AI.
75
+
-**Checking your file.**`tests/unit/language-parity.test.ts` fails if a language file has a key that is not in `_language.yml`, misses a key, or changes the placeholders. If you add an English key that you cannot translate, add its language entries to `tests/unit/language-known-gaps.yml` instead.
0 commit comments