Skip to content
Pauta6.1.0

Internationalization

Every app ships in at least six languages, and the user’s language is chosen the same way in each. Every string the user reads comes from a message catalog by its key, and the rules keep each catalog in step with the English base, keep each message right in its language (apostrophes, numbers, plurals), keep the layout whole in the longest language, and leave alone what must read the same everywhere: command ids, setting keys, file names, chord modifiers and the --help text.

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 14
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 the catalog, by its key, through one lookup in one class (tr("some.key") in Editora’s Messages).
INTL-08MUST
Every catalog has every key of the base catalog, and no more, each with a non-empty value.
INTL-09SHOULD
In a catalog value with a placeholder, a literal apostrophe is doubled; in a value without one, it is written once. Inside a {0,choice,…} limb (INTL-12) that itself holds a placeholder, it is written four times; in a limb without one it is doubled, like the rest of the value.
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’s modifiers read the same in every language: Ctrl, Alt, Shift and the macOS glyphs are never translated (“Ctrl”, not “Strg”).
INTL-14MUST
The app starts in the language the user chose in its settings, where it offers that choice; with none chosen, in the system’s language when it ships a catalog for it; otherwise in English. The locale that formats dates and numbers keeps the system’s region: with no language chosen it is the system’s locale whole, whatever language the menus are in, and with one chosen it is still the system’s locale when that is the system’s own language, and the bare language only when it is another. That locale is the JVM’s default once the app has started: the app sets it wherever it is not the locale the JVM started with. The message catalog formats its values with it too, never with a locale of its own made from the bare language.

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.
    • Check (by hand): run the app in each language with the window 1024 px wide, open each window and Settings page, and find no row cut off.
    • Reference: Editora messages_de.properties.
  • 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 the catalog, by its key, through one lookup in one class (tr("some.key") in Editora’s Messages).
    • Check (code): no source file passes a string literal in a text position: a control’s constructor, setText, setPromptText, setTitle, a tooltip, a menu item or a command’s label. Each takes its text from the catalog’s lookup, which is one method of one class (Editora’s Messages.tr). A test that scans the sources and fails on such a literal is the surest evidence.
    • Reference: Editora i18n/Messages.java. The tests that hold the rule are Torrenta’s UiStringSweepTest (noStringLiteralInATextPosition) and nux’s NoLiteralUiTextTest (userFacingTextGoesThroughTheCatalogue). Editora’s MessagesTest.everyLiteralKeyUsedInTheSourcesExists checks only that every key a tr("…") call names is in the base catalog, not that no literal reaches a control.
  • INTL-08 MUST Every catalog has every key of the base catalog, and no more, each with a non-empty value.
    • Check (code): compare each translated catalog’s keys with the base catalog’s: none is missing, none is extra, and no value is empty. A parity test that fails the build on any of the three is the surest evidence.
    • Reference: Editora MessagesTest.translationCatalogsHaveExactlyTheBaseKeySet, translationsAreNonEmptyAndDistinctFromKeys.
  • INTL-09 SHOULD In a catalog value with a placeholder, a literal apostrophe is doubled; in a value without one, it is written once. Inside a {0,choice,…} limb (INTL-12) that itself holds a placeholder, it is written four times; in a limb without one it is doubled, like the rest of the value.
    • 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. A choice limb that holds a placeholder is parsed a second time as a pattern of its own, and each pass halves the apostrophes.
    • Check (code): in every catalog, a value with a placeholder has no lone apostrophe and a value without one has no doubled apostrophe; a choice limb that holds a placeholder writes a literal apostrophe four times, and a limb that holds none writes it twice. Catalog tests that fail each of the four mistakes are the surest evidence.
    • Reference: Editora MessagesTest.aValueWithAPlaceholderNeverHasALoneApostrophe, aValueWithoutAPlaceholderNeverDoublesAnApostrophe. The choice limbs are held by Torrenta’s MessagesTest.apostrophesInsideChoiceLimbsAreQuotedForTheRightNumberOfPasses (diagnosis.unavailable in its messages_fr.properties writes “n''''est” in a limb with {1}); Editora’s test has no such case.
  • INTL-10 SHOULD Identifiers such as line numbers and ports use {0,number,#}, so they are not digit-grouped.
    • Check (code): in every catalog, a placeholder the code fills with an identifier (a line number, a port) carries the number,# format, as in {0,number,#}, and is never a bare {0}. A test that formats each identifier argument in every locale and fails on a grouped number is the surest evidence.
    • Reference: Editora MessagesTest.identifierArgumentsAreNeverDigitGrouped.
  • 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 (code): compare each translated catalog with the base, key by key: a command id, a setting key, a file name or a protocol name in the base value appears, spelled the same, in the translated value. A made-up example name inside a value (name.gpg) is not an identifier, and may be translated.
    • 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)”.
    • Why: “(s)” is English; other languages change more than one ending, and the translator can only get it right with the forms written out.
    • Check (code): no catalog value has a placeholder and (s); a message with a count has a {0,choice,…} pattern with a limb for each form its language needs, and every such pattern parses. A catalog test that fails a value with a placeholder and (s), and parses every choice pattern in every catalog, is the surest evidence.
    • Reference: Torrenta’s omni.targets.matching in messages.properties, parsed in every language by MessagesTest.placeholdersMatchAcrossLanguagesAndEveryPatternParses. That test only parses the patterns: no app has the (s) test yet, and Editora’s base catalog has 22 values with a placeholder and (s) (find.replaced, “Replaced {0} occurrence(s)”).
  • INTL-13 SHOULD A chord’s modifiers read 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, and no catalog value writes a modifier in another language: a catalog test looks for Strg, Umschalt, Maj, Mayús and Maiusc.
    • Reference: Editora command/ChordFormat.java writes chords with untranslated modifiers. Its catalogs do not hold the rule yet: they translate modifiers in prose (“Strg+D”, “Mayús+Tab”, “Maj+Entrée”) and in the Project Map help’s key names (messages_de.properties, project.map.help.key.control=Strg, read by ui/ProjectMapHelp.java). No app has the catalog test yet.
  • INTL-14 MUST The app starts in the language the user chose in its settings, where it offers that choice; with none chosen, in the system’s language when it ships a catalog for it; otherwise in English. The locale that formats dates and numbers keeps the system’s region: with no language chosen it is the system’s locale whole, whatever language the menus are in, and with one chosen it is still the system’s locale when that is the system’s own language, and the bare language only when it is another. That locale is the JVM’s default once the app has started: the app sets it wherever it is not the locale the JVM started with. The message catalog formats its values with it too, never with a locale of its own made from the bare language.
    • Why: de-AT collapsed to de writes an Austrian’s numbers and dates the German way, and an English UI on a French system has no reason to change how its dates are written. Apps that settle this differently format the same date two ways side by side, and so does one app whose catalog formats a message’s number with another locale than the rest of the window.
    • Check (code): the start-up code takes the stored choice, the system’s locale and the catalogs the app ships and gives the language and the locale as the four cases ask: none chosen with a catalog for the system’s language (the system’s locale whole); none chosen without one (English, the system’s locale kept whole); the system’s own language chosen (its region kept); another language chosen (the bare language). It sets that locale as the JVM’s default (Locale.setDefault) as it starts, wherever that is not the locale the JVM started with: an app that offers no language choice and ships no catalogs leaves the default alone, which is the system’s locale whole, and meets this part. And the catalog’s lookup formats a value with the default locale (new MessageFormat(pattern), or MessageFormat.format), not with one it builds from the language code (Locale.forLanguageTag). A test that covers the four cases is the surest evidence.
    • Reference: Termina i18n/Messages.java (resolve, defaultLocale, and tr, which formats with the default locale) with MessagesTest.java (automaticKeepsTheOperatingSystemsLocaleWhole, anExplicitChoiceMovesTheLocaleButKeepsAMatchingCountry). Torrenta carries the same two functions and tests and sets the default from them (Startup.java, language), but doesn’t meet the rule yet: its catalog formats every message with the bare language (i18n/Messages.java, locale), so a number inside a message loses the region the rest of the window keeps. nux’s i18n/Messages.java (uiLocale, UiLocaleTest) keeps the region when the language is the system’s, but with none chosen and no catalog for the system’s language it sets bare English. Editora (App.java) and Mirada (App.java) set the default to the bare language every time, so the region is lost; Mirada’s catalog formats with the bare language as well (i18n/Messages.java). The app template meets it: its i18n/Messages.java gives the four cases (locale), sets the result as the JVM’s default where it differs (start) and formats with new MessageFormat(value) (render); its MessagesTest (theFormattingLocaleKeepsTheSystemsRegion) covers the four. Modula ships no catalogs and offers no language choice, and leaves the JVM’s locale as the system set it, which is the locale the rule asks for: it meets this rule, and its missing catalogs are INTL-01’s.
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 6.1.0 · · Changelog · This page in the latest edition