Settle “Kind” or “Type” in the interface, once, before more languages are filled #705

New issue

Closed

opened 2026-10-03 01:59:14 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-03 01:59:14 +00:00

Owner

What exists today

Counted on 2026-10-02 in src/postulo/locale/fr_FR/LC_MESSAGES/django.po (3,124 entries) and the templates, at f09b6010b:

46 message ids contain the word kind or kinds, and 26 contain type or types. The 26 are mostly the verb (“Type the identifier.”, “Type it in instead”). The noun, for a classification, appears as “Employment type” (src/postulo/applications/forms.py:119, src/postulo/jobs/models.py:888, :1496), “an unknown file type”, a media type in “That address is %(type)s…”, a “document type declaration”, and Type for typography.
“kind” as a label. _("kind") is the label of 15 model fields: applications/models.py:548, :712, :844; core/models.py:305, :548, :698, :811; documents/models.py:258, :512, :579, :718; jobs/models.py:252, :1373; plugins/models.py:192; resume/models.py:306. Kind stands alone as a label or heading in seven places: jobs/tables.py:94 (the companies table's column), templates/applications/report.html:54, templates/cotton/identifier_row.html:24, templates/jobs/capture_page.html:90, templates/partials/phone_numbers.html:61, templates/partials/postal_addresses.html:71, templates/server/design.html:195. The rest of the 46 are sentences (“Choose what kind of identifier this is.”, “No letters of this kind yet.”, “Kinds of letter”) and %(kind)s placeholders, which are code names and unaffected.
One of the seven is the wrong word altogether. report.html:54 labels the report's period selector (a month, a quarter, the last few weeks, dates you choose) “Kind”.
The two working languages already settled it. French translates Kind as “Type” and 28 of the 46 strings with “type”, once with “genre” in an idiom (“ce genre de chose”); Portuguese translates 29 with “tipo”. “Genre” and “Género” are used for nothing else in either catalogue. Besides French and the two Portuguese catalogues (European and Brazilian, which carry all 46), 36 more catalogues carry drafts for these strings, and they say sort far more often than type: German “Art”, Dutch “Soort”, Polish “Rodzaj”, Czech and Slovak “Druh”, Croatian and Slovene “Vrsta”, Estonian “Liik”, against “Tipo”, “Typ”, “Type”, “Tip” in the Romance, Scandinavian and some other languages. All are flagged draft.
msgid "Type" already means typography. Section("type", _("Type")) in src/postulo/core/design.py:131 and the heading at src/postulo/templates/server/design.html:99; French and Portuguese translate it “Typographie” and “Tipografia”. A message id with two meanings is one entry: postulo.core.messages_tool keys messages by (context, msgid) and merge carries one translation per key (src/postulo/core/messages_tool.py:578-606), so renaming Kind to Type would silently give the design page “Type” in French, and gettext's own compiler refuses a duplicate id. The tool supports pgettext (messages_tool.py:119-122), already used (src/postulo/plugins/builtin/patterns.py:41).
A rename drops translations. merge “drops what the source lost” (tests/test_messages_tool.py:100): a changed message id arrives empty in all 68 catalogues, and the 39 that carry these strings lose them. The tool has no rename command.
The docs use both words as well. The wiki names the UI label Kind in Tracking-applications.md:721 and :729, Your-career-record.md:178, and as table headers (Cover-letters.md:5, Your-career-record.md:585); docs/TRANSLATING.md:192-205 talks of “kinds of letter”.
In code, kind is the name everywhere: CompanyKind, DocumentKind, kinds.register, the API's kind fields, the archive's keys, the plugin entry-point kind=.

Checked against main at f09b6010b.

Proposal

Say the rule in docs/TRANSLATING.md and the contributor guide: in the interface, what a person picks from a list to say what sort a thing is is called its Type; kind stays in code, in the API, in the archive and in the plugin contract.
One sweep commit changes the 15 field labels, the seven standalone labels and the headings that name the field (“Kinds of letter”, “Kinds of entry”, “Start from a kind”, “kind of document”, “kind of entry”, “kind of source”, “kind of rendering”, “kind of thing it points at”) to type, and the sentences that point at the field.
Give typography its own message: Typography (French and Portuguese already have “Typographie” and “Tipografia”) on the design page, so Type means one thing.
Carry the translations over in the same commit with a one-off script that copies each old message id's translation to its new id in every catalogue, keeping its draft flag; then scripts/messages.py extract --check and check pass.
Fix the period selector: report.html:54 reads “Period”.
Update the wiki and the contributor docs where they name the label Kind, and say in TRANSLATING.md which words a translator should not use for it (below).
Do it before the next strings arrive. The list adds a gender field, instant-messaging contacts, publications and more sections, each of which would otherwise add another “kind” label.

Decisions

Kind or Type. Recommended: Type, for four reasons. English interfaces use “Type” for a list that classifies something (the product already says “Employment type”); French and Portuguese already say “type” and “tipo” and keep doing so; “Kind” is a word a translator can reach for “genre” or “sort” from, and French genre is also the natural word for the gender field the list asks for (#681), where a clash is easy to cause and hard to see; and the 36 draft translations that say sort are drafts nobody has reviewed. Where the maintainer prefers “Kind”, nothing changes in French or Portuguese; only the typography collision and the period label need fixing.
How much of the prose. The label and heading only, or every sentence that says “kind”. Recommended: labels, headings and the sentences that name the field to the person using it (“Choose the type of identifier.”); leave idioms (“this kind of thing”) as they are, since “kind of” is ordinary English.
The typography string. A pgettext context on Type, or a new message Typography. Recommended: Typography, which is also the better English for a design page's heading.
When. Before #269's next languages are filled and in the same release as #349's round trip, so Weblate sees one change and not two; or at once. Recommended: at once in the repository, with the carry-over script, because the strings are drafts and the sweep touches only the three working catalogues in full.
The glossary. #349 notes the Weblate glossary is unusable. Recommended: put the rule in TRANSLATING.md until it is not, with “Type” (not “genre” or “sort”) named for the field.

Builds on

Issues #349 (the Weblate round trip), #347 (the per-commit gate), #269 (the next languages; “one sweep, before more languages are filled”). Related: #706, #690 (the same kind of rename for “Programming languages”), #681.

Done when

grep finds no label or heading that says “Kind” or “kind” in the interface strings listed above; the wiki and docs/TRANSLATING.md say Type.
A test in tests/test_translations.py (or beside tests/test_messages_tool.py) fails if a message id is used both with and without a context, or if Kind reappears as a standalone label, and the three working catalogues carry the translations of every renamed id (French “Type”, Portuguese “Tipo”, British English the source) with no entry lost: scripts/messages.py extract --check and check pass.
The design page reads “Typography” in the three working languages; the report's selector reads “Period”.
No record type is added, so no format changes (the archive is 29 and the candidate format 4 at f09b6010b, untouched); new strings are in the working catalogues (en-GB, fr-FR, pt-PT as drafts) and Weblate (#349).

From the list of improvements of 2026-10-02.

From the list: “‘Kind’ or ‘Type’, which is the most accurate term.” The interface uses both words for the same thing, in the same screens, and every language translates whichever it finds. Settling it now costs a catalogue edit in three working languages; later it costs the drafts of all the others. ## What exists today Counted on 2026-10-02 in `src/postulo/locale/fr_FR/LC_MESSAGES/django.po` (3,124 entries) and the templates, at `f09b6010b`: - **46 message ids contain the word kind or kinds, and 26 contain type or types.** The 26 are mostly the verb (“Type the identifier.”, “Type it in instead”). The noun, for a classification, appears as “Employment type” (`src/postulo/applications/forms.py:119`, `src/postulo/jobs/models.py:888`, `:1496`), “an unknown file type”, a media type in “That address is %(type)s…”, a “document type declaration”, and `Type` for typography. - **“kind” as a label.** `_("kind")` is the label of 15 model fields: `applications/models.py:548`, `:712`, `:844`; `core/models.py:305`, `:548`, `:698`, `:811`; `documents/models.py:258`, `:512`, `:579`, `:718`; `jobs/models.py:252`, `:1373`; `plugins/models.py:192`; `resume/models.py:306`. `Kind` stands alone as a label or heading in seven places: `jobs/tables.py:94` (the companies table's column), `templates/applications/report.html:54`, `templates/cotton/identifier_row.html:24`, `templates/jobs/capture_page.html:90`, `templates/partials/phone_numbers.html:61`, `templates/partials/postal_addresses.html:71`, `templates/server/design.html:195`. The rest of the 46 are sentences (“Choose what kind of identifier this is.”, “No letters of this kind yet.”, “Kinds of letter”) and `%(kind)s` placeholders, which are code names and unaffected. - **One of the seven is the wrong word altogether.** `report.html:54` labels the report's period selector (a month, a quarter, the last few weeks, dates you choose) “Kind”. - **The two working languages already settled it.** French translates `Kind` as “Type” and 28 of the 46 strings with “type”, once with “genre” in an idiom (“ce genre de chose”); Portuguese translates 29 with “tipo”. “Genre” and “Género” are used for nothing else in either catalogue. Besides French and the two Portuguese catalogues (European and Brazilian, which carry all 46), 36 more catalogues carry drafts for these strings, and they say *sort* far more often than *type*: German “Art”, Dutch “Soort”, Polish “Rodzaj”, Czech and Slovak “Druh”, Croatian and Slovene “Vrsta”, Estonian “Liik”, against “Tipo”, “Typ”, “Type”, “Tip” in the Romance, Scandinavian and some other languages. All are flagged `draft`. - **`msgid "Type"` already means typography.** `Section("type", _("Type"))` in `src/postulo/core/design.py:131` and the heading at `src/postulo/templates/server/design.html:99`; French and Portuguese translate it “Typographie” and “Tipografia”. A message id with two meanings is one entry: `postulo.core.messages_tool` keys messages by (context, msgid) and `merge` carries one translation per key (`src/postulo/core/messages_tool.py:578-606`), so renaming `Kind` to `Type` would silently give the design page “Type” in French, and gettext's own compiler refuses a duplicate id. The tool supports `pgettext` (`messages_tool.py:119-122`), already used (`src/postulo/plugins/builtin/patterns.py:41`). - **A rename drops translations.** `merge` “drops what the source lost” (`tests/test_messages_tool.py:100`): a changed message id arrives empty in all 68 catalogues, and the 39 that carry these strings lose them. The tool has no rename command. - **The docs use both words as well.** The wiki names the UI label *Kind* in `Tracking-applications.md:721` and `:729`, `Your-career-record.md:178`, and as table headers (`Cover-letters.md:5`, `Your-career-record.md:585`); `docs/TRANSLATING.md:192-205` talks of “kinds of letter”. - **In code, `kind` is the name everywhere**: `CompanyKind`, `DocumentKind`, `kinds.register`, the API's `kind` fields, the archive's keys, the plugin entry-point `kind=`. Checked against `main` at `f09b6010b`. ## Proposal 1. **Say the rule in `docs/TRANSLATING.md` and the contributor guide**: in the interface, what a person picks from a list to say what sort a thing is is called its *Type*; `kind` stays in code, in the API, in the archive and in the plugin contract. 2. **One sweep commit** changes the 15 field labels, the seven standalone labels and the headings that name the field (“Kinds of letter”, “Kinds of entry”, “Start from a kind”, “kind of document”, “kind of entry”, “kind of source”, “kind of rendering”, “kind of thing it points at”) to *type*, and the sentences that point at the field. 3. **Give typography its own message**: `Typography` (French and Portuguese already have “Typographie” and “Tipografia”) on the design page, so `Type` means one thing. 4. **Carry the translations over in the same commit** with a one-off script that copies each old message id's translation to its new id in every catalogue, keeping its `draft` flag; then `scripts/messages.py extract --check` and `check` pass. 5. **Fix the period selector**: `report.html:54` reads “Period”. 6. **Update the wiki and the contributor docs** where they name the label *Kind*, and say in `TRANSLATING.md` which words a translator should not use for it (below). 7. **Do it before the next strings arrive.** The list adds a gender field, instant-messaging contacts, publications and more sections, each of which would otherwise add another “kind” label. ## Decisions - **Kind or Type.** **Recommended: Type**, for four reasons. English interfaces use “Type” for a list that classifies something (the product already says “Employment type”); French and Portuguese already say “type” and “tipo” and keep doing so; “Kind” is a word a translator can reach for “genre” or “sort” from, and French *genre* is also the natural word for the gender field the list asks for (#681), where a clash is easy to cause and hard to see; and the 36 draft translations that say *sort* are drafts nobody has reviewed. Where the maintainer prefers “Kind”, nothing changes in French or Portuguese; only the typography collision and the period label need fixing. - **How much of the prose.** The label and heading only, or every sentence that says “kind”. **Recommended: labels, headings and the sentences that name the field to the person using it** (“Choose the type of identifier.”); leave idioms (“this kind of thing”) as they are, since “kind of” is ordinary English. - **The typography string.** A `pgettext` context on `Type`, or a new message `Typography`. **Recommended: `Typography`**, which is also the better English for a design page's heading. - **When.** Before #269's next languages are filled and in the same release as #349's round trip, so Weblate sees one change and not two; or at once. **Recommended: at once in the repository**, with the carry-over script, because the strings are drafts and the sweep touches only the three working catalogues in full. - **The glossary.** #349 notes the Weblate glossary is unusable. **Recommended: put the rule in `TRANSLATING.md` until it is not**, with “Type” (not “genre” or “sort”) named for the field. ## Builds on Issues #349 (the Weblate round trip), #347 (the per-commit gate), #269 (the next languages; “one sweep, before more languages are filled”). Related: #706, #690 (the same kind of rename for “Programming languages”), #681. ## Done when - `grep` finds no label or heading that says “Kind” or “kind” in the interface strings listed above; the wiki and `docs/TRANSLATING.md` say Type. - A test in `tests/test_translations.py` (or beside `tests/test_messages_tool.py`) fails if a message id is used both with and without a context, or if `Kind` reappears as a standalone label, and the three working catalogues carry the translations of every renamed id (French “Type”, Portuguese “Tipo”, British English the source) with no entry lost: `scripts/messages.py extract --check` and `check` pass. - The design page reads “Typography” in the three working languages; the report's selector reads “Period”. - No record type is added, so no format changes (the archive is 29 and the candidate format 4 at `f09b6010b`, untouched); new strings are in the working catalogues (en-GB, fr-FR, pt-PT as drafts) and Weblate (#349). From the list of improvements of 2026-10-02.

tiagoagueda added this to the 0.5.0 milestone

2026-10-03 01:59:14 +00:00

tiagoagueda added the

interface

internationalisation

enhancement

labels

2026-10-03 01:59:14 +00:00

tiagoagueda referenced this issue

2026-10-03 01:59:14 +00:00

Translations are made in Weblate only: the rule, the documents that contradict it, and what a commit does with a string #706

tiagoagueda referenced this issue