Skip to content
Pauta5.0.0

Internationalization

Reference: Editora’s i18n/Messages.java (tr, and available() behind the Settings language picker), the catalogs in src/main/resources/com/editora/i18n/, and i18n/MessagesTest.java, which holds them in step.

Rules on this page 13
IDLevelRule
Languages
INTL-01MUST
The app ships a message catalog for each of at least six languages: English (the base), Spanish, Portuguese, French, Italian and German.
INTL-02SHOULD
A new language is a messages_<code>.properties with every key, listed in the Settings language picker and in the parity test.
INTL-03SHOULD
Every value is translated for real: no English value is shipped in another language’s catalog.
INTL-04SHOULD
The layout holds in every language at 1024 px wide: rows wrap, never cut. German is today’s longest.
INTL-05SHOULD
A Chinese, Japanese or Korean catalog comes with a font fallback for its script.
INTL-06SHOULD
An Arabic or Hebrew catalog sets NodeOrientation.RIGHT_TO_LEFT on every scene.
Rules
INTL-07SHOULD
No raw English literal is passed to a control: every string comes from tr("some.key") in one Messages class.
INTL-08MUST
Every catalog has every key of the base catalog, and no more, each with a non-empty value.
INTL-09SHOULD
In a value with a placeholder, a literal apostrophe is doubled; in a value without one, it is written once.
INTL-10SHOULD
Identifiers such as line numbers and ports use {0,number,#}, so they are not digit-grouped.
INTL-11SHOULD
Technical identifiers stay untranslated: command ids, setting keys, file names and protocol names read the same in every language. The --help and --version text is CLI-01.
INTL-12SHOULD
A message with a count words it for the count, with a {0,choice,…} limb for each form the language needs: never “file(s)”.
INTL-13SHOULD
A chord reads the same in every language: Ctrl, Alt, Shift and the macOS glyphs are never translated (“Ctrl”, not “Strg”).

Every app ships at least these six. They are a floor, not the set: an app SHOULD add languages as people ask for them, and a new app can start with more.

LanguageCatalog
English (base)messages.properties
Spanishmessages_es.properties
Portuguesemessages_pt.properties
Frenchmessages_fr.properties
Italianmessages_it.properties
Germanmessages_de.properties
  • INTL-01 MUST The app ships a message catalog for each of at least six languages: English (the base), Spanish, Portuguese, French, Italian and German.

Adding a language:

  • INTL-02 SHOULD A new language is a messages_<code>.properties with every key, listed in the Settings language picker and in the parity test.
    • Check (code): the language’s code is in Messages’ language list (which the picker shows) and in the catalog list the parity test walks.
    • Reference: Editora i18n/Messages.java (LANGUAGES, available()); MessagesTest’s LOCALES and ALL_CATALOGS, after which translationCatalogsHaveExactlyTheBaseKeySet holds it to the same keys as the others.
  • INTL-03 SHOULD Every value is translated for real: no English value is shipped in another language’s catalog.
    • Check (code): compare each catalog’s values with the base; a value identical to the English one is a name, a term or a bare pattern that stays the same in that language (“Git: Pull (Rebase)”, “{0} · {1}”), never an untranslated sentence. No test catches it, so it is also checked in review.
    • Reference: Editora messages_*.properties.
  • INTL-04 SHOULD The layout holds in every language at 1024 px wide: rows wrap, never cut. German is today’s longest.
  • INTL-05 SHOULD A Chinese, Japanese or Korean catalog comes with a font fallback for its script.
    • Why: Inter has no CJK glyphs. JavaFX falls back to whatever font the OS has, so without a bundled one the text looks different on each OS, and a minimal Linux install may have none.
    • Check (by hand): run the app in that language and look for missing-glyph boxes.
    • Reference: no app yet.
  • INTL-06 SHOULD An Arabic or Hebrew catalog sets NodeOrientation.RIGHT_TO_LEFT on every scene.
    • Check (code): the scene setup sets the node orientation from the current language.
    • Reference: no app yet.
  • INTL-07 SHOULD No raw English literal is passed to a control: every string comes from tr("some.key") in one Messages class.
  • INTL-08 MUST Every catalog has every key of the base catalog, and no more, each with a non-empty value.
  • INTL-09 SHOULD In a value with a placeholder, a literal apostrophe is doubled; in a value without one, it is written once.
    • Why: a value with a placeholder is a MessageFormat pattern, where a lone apostrophe starts a quoted section and can swallow the placeholder after it; a value without one is shown exactly as written.
    • Check (test): catalog tests fail a lone apostrophe beside a placeholder and a doubled one without.
    • Reference: Editora MessagesTest.aValueWithAPlaceholderNeverHasALoneApostrophe, aValueWithoutAPlaceholderNeverDoublesAnApostrophe.
  • INTL-10 SHOULD Identifiers such as line numbers and ports use {0,number,#}, so they are not digit-grouped.
  • INTL-11 SHOULD Technical identifiers stay untranslated: command ids, setting keys, file names and protocol names read the same in every language. The --help and --version text is CLI-01.
    • Check (by hand): in a translated catalog, every command id, setting key and file name appears as written.
    • Reference: Editora’s catalogs (messages.properties and its translations).
  • INTL-12 SHOULD A message with a count words it for the count, with a {0,choice,…} limb for each form the language needs: never “file(s)”.
  • INTL-13 SHOULD A chord reads the same in every language: Ctrl, Alt, Shift and the macOS glyphs are never translated (“Ctrl”, not “Strg”).
    • Why: the keymaps, the docs and the screenshots use one spelling, and a user who changes the language keeps the chords they learned.
    • Check (code): the code that writes a chord out takes its modifier names from constants, not the catalog.
    • Reference: Editora command/ChordFormat.java.
Editora with a Spanish interface
Editora in Spanish: menus, tool windows and the status bar all come from the catalogs.
Torrenta with a Spanish interface
Torrenta in Spanish.

Pauta 5.0.0 · · Changelog · This page in the latest edition