Give every template its translations, in the plugin's own catalogues, and hold them complete

tiagoagueda commented

2026-10-01 07:02:06 +00:00

Owner

The list says: "Every template must hold its translations in order to produce multilanguage documents."

What the core does today

A plugin's locale/ is joined to the catalogues when the plugin loads (src/postulo/plugins/locale.py in the core), and postulo-messages extract reads the templates inside the package. A template's own words are therefore translated from this plugin's catalogues.
A document is drawn in its own language, not the reader's: the render runs inside the document's language (postulo/postulo#223, postulo/postulo#283).
Section titles come from the core, already in the document's language (section.label). A template translates only the words it adds.
Where the core and a plugin have the same English string, the core's translation wins.

Reading

"Hold its translations" is read as: every template's words are in this plugin's catalogues, and every template is complete in every language the plugin ships. The alternative, a catalogue per template, is not how the core loads catalogues and would be a core change; it is not proposed.

What the plugin should do

Every visible word of every template is marked for translation. No text inside an image or a drawing (#8); a word that must sit in a graphic is set as text over it.
Dates, numbers and the order of an address follow the document's language.
Every template honours the document's direction, with logical properties in its CSS, so one template serves left-to-right and right-to-left languages.
A test draws each template in each language the plugin ships and fails on a string left in English.
The catalogue rule of the other official plugins: French and European Portuguese filled on every commit, the European Union languages complete before a tag (uv run pytest -m release).
Language codes are written as postulo/postulo#337 decided: BCP 47 tags in canonical form (pt-BR). The locale/ directory names are gettext's and made by the tool.

Decisions

Which languages. Recommended: the rule above, the same as every official plugin. Alternative: every language Postulo offers, on every commit.
A template not yet translated into a language. The core cannot be told which languages a theme covers, so an untranslated word falls back to English with no warning. Recommended: the release gate keeps every template complete, so the case does not arise. If partial coverage is ever wanted, the core would need a declaration and a warning in the picker; not filed.

Needs from the core

Nothing.

Done when

A CV whose language is French, drawn with each template, has no English word that the template wrote.
A document in a right-to-left language is laid out right to left by every template.
The release gate fails when a template gains a string that a European Union catalogue lacks.

From the list of template improvements of 2026-09-30.

The list says: "Every template must hold its translations in order to produce multilanguage documents." ## What the core does today - A plugin's `locale/` is joined to the catalogues when the plugin loads (`src/postulo/plugins/locale.py` in the core), and `postulo-messages extract` reads the templates inside the package. A template's own words are therefore translated from this plugin's catalogues. - A document is drawn in its own language, not the reader's: the render runs inside the document's language (postulo/postulo#223, postulo/postulo#283). - Section titles come from the core, already in the document's language (`section.label`). A template translates only the words it adds. - Where the core and a plugin have the same English string, the core's translation wins. ## Reading "Hold its translations" is read as: every template's words are in this plugin's catalogues, and every template is complete in every language the plugin ships. The alternative, a catalogue per template, is not how the core loads catalogues and would be a core change; it is not proposed. ## What the plugin should do - Every visible word of every template is marked for translation. No text inside an image or a drawing (#8); a word that must sit in a graphic is set as text over it. - Dates, numbers and the order of an address follow the document's language. - Every template honours the document's direction, with logical properties in its CSS, so one template serves left-to-right and right-to-left languages. - A test draws each template in each language the plugin ships and fails on a string left in English. - The catalogue rule of the other official plugins: French and European Portuguese filled on every commit, the European Union languages complete before a tag (`uv run pytest -m release`). - Language codes are written as postulo/postulo#337 decided: BCP 47 tags in canonical form (`pt-BR`). The `locale/` directory names are gettext's and made by the tool. ## Decisions - **Which languages.** Recommended: the rule above, the same as every official plugin. Alternative: every language Postulo offers, on every commit. - **A template not yet translated into a language.** The core cannot be told which languages a theme covers, so an untranslated word falls back to English with no warning. Recommended: the release gate keeps every template complete, so the case does not arise. If partial coverage is ever wanted, the core would need a declaration and a warning in the picker; not filed. ## Needs from the core Nothing. ## Done when - A CV whose language is French, drawn with each template, has no English word that the template wrote. - A document in a right-to-left language is laid out right to left by every template. - The release gate fails when a template gains a string that a European Union catalogue lacks. From the list of template improvements of 2026-09-30.

tiagoagueda added the

enhancement

label

2026-10-01 07:02:06 +00:00

tiagoagueda referenced this issue

2026-10-01 07:02:06 +00:00

Give every template its own assets: fonts, logos and icons, vector first, so that they print #8

tiagoagueda commented

2026-10-01 10:00:19 +00:00

Author

Owner

Final decision on translations (maintainer, 2026-10-01)

Every language is scaffolded: each has its catalogue, with a slot for every string.
A development build requires every string to be present in en-GB, fr-FR and pt-PT. A draft counts.
A release requires every string to be present in the languages selected for that release. A draft counts.
0.4.0 requires no additional languages.
0.5.0 additionally requires fr-CA and en-CA; then, eventually, any language of the European continent still missing (Russian excepted); and, eventually, Chinese and Arabic. Those last two may move to 0.6.0 if the load on 0.5.0 becomes too great.

What this changes here

"Hold them complete" now has a definition, the same as the core's:

While developing, every template's words are present in en-GB, fr-FR and pt-PT.
For a release, in the languages selected for that release. A draft counts in both.
The plugin's catalogues are scaffolded for every language, like the core's; a language nobody has translated is simply not offered for a document.
Next to arrive: fr-CA and en-CA (0.5.0), then the European languages still missing, then Chinese and Arabic. Those two are where this issue's points about fonts and direction stop being theoretical: a template has to draw the script and honour right-to-left before the language can be selected.

**Final decision on translations (maintainer, 2026-10-01)** 1. **Every language is scaffolded**: each has its catalogue, with a slot for every string. 2. **A development build** requires every string to be present in **en-GB, fr-FR and pt-PT**. A draft counts. 3. **A release** requires every string to be present in **the languages selected for that release**. A draft counts. 4. **0.4.0** requires no additional languages. 5. **0.5.0** additionally requires **fr-CA** and **en-CA**; then, eventually, any language of the European continent still missing (Russian excepted); and, eventually, **Chinese** and **Arabic**. Those last two may move to 0.6.0 if the load on 0.5.0 becomes too great. ## What this changes here "Hold them complete" now has a definition, the same as the core's: - **While developing**, every template's words are present in **en-GB, fr-FR and pt-PT**. - **For a release**, in the languages selected for that release. A draft counts in both. - The plugin's catalogues are **scaffolded for every language**, like the core's; a language nobody has translated is simply not offered for a document. - **Next to arrive:** fr-CA and en-CA (0.5.0), then the European languages still missing, then Chinese and Arabic. Those two are where this issue's points about fonts and direction stop being theoretical: a template has to draw the script and honour right-to-left before the language can be selected.

tiagoagueda referenced this issue from Postulo/postulo

2026-10-01 10:06:12 +00:00

Translations: hold a development build to en-GB, fr-FR and pt-PT and a release to its selected languages, with every language scaffolded #347

tiagoagueda commented

2026-10-01 10:06:16 +00:00

Author

Owner

Follow-up to the final decision on translations (maintainer, 2026-10-01)

Chinese: both. Simplified and traditional, two catalogues (zh-Hans, zh-Hant).
"European" means the continent, not the European Union. Turkish and Icelandic count; they are already carried.
Every component moves with the core, language-wise, plugins and extensions included.

The work is postulo/postulo#347.

**Follow-up to the final decision on translations (maintainer, 2026-10-01)** - **Chinese: both.** Simplified and traditional, two catalogues (`zh-Hans`, `zh-Hant`). - **"European" means the continent, not the European Union.** Turkish and Icelandic count; they are already carried. - **Every component moves with the core, language-wise**, plugins and extensions included. The work is postulo/postulo#347.

tiagoagueda referenced this issue

2026-10-01 10:14:22 +00:00

Translations: a working round trip between this repository and its Weblate project on translate.tiagoagueda.com #10

tiagoagueda referenced this issue

2026-10-01 10:39:56 +00:00

A first test CV template from the official Europass template, if its licence allows #12

tiagoagueda referenced this issue from a commit

2026-10-10 12:06:04 +00:00

Say where this repository's words will be translated

tiagoagueda referenced this issue

2026-10-19 07:14:59 +00:00

Pin the uv installer, audit the lock and repin the dev core #16