Skip to content
Pauta4.2.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 11
IDLevelRule
Languages
INTL-01MUST
The app ships a message catalog for each of the six languages above, English as the base.
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 and the --help and --version text stay untranslated, outside the catalogs.

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 the six languages above, English as the base.

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.
    • 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 and the --help and --version text stay untranslated, outside the catalogs.
    • Check (code): the usage text is a literal in the launcher, not a tr call.
    • Reference: Editora App.java (the usage text).
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 4.2.0 · · Changelog · This page in the latest edition