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
| ID | Level | Rule |
|---|---|---|
| Languages | ||
| 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.
|
| 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.
|
| INTL-03 | SHOULD | Every value is translated for real: no English value is shipped in another language’s
catalog.
|
| 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.
|
| INTL-06 | SHOULD | An Arabic or Hebrew catalog sets NodeOrientation.RIGHT_TO_LEFT on every scene.
|
| Rules | ||
| 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).
|
| 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 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-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.
|
| 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’s modifiers read the same in every language: Ctrl, Alt, Shift and the macOS
glyphs are never translated (“Ctrl”, not “Strg”).
|
| 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.
|
Languages
Section titled “Languages”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.
| Language | Catalog |
|---|---|
| English (base) | messages.properties |
| Spanish | messages_es.properties |
| Portuguese | messages_pt.properties |
| French | messages_fr.properties |
| Italian | messages_it.properties |
| German | messages_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.
- Check (code): the six
messages*.propertiesfiles are in the app’si18nresources. - Reference: Editora
src/main/resources/com/editora/i18n/.
- Check (code): the six
Adding a language:
- INTL-02 SHOULD A new language is a
messages_<code>.propertieswith 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’sLOCALESandALL_CATALOGS, after whichtranslationCatalogsHaveExactlyTheBaseKeySetholds it to the same keys as the others.
- Check (code): the language’s code is in
- 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_LEFTon 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’sMessages).- 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’sMessages.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’sUiStringSweepTest(noStringLiteralInATextPosition) and nux’sNoLiteralUiTextTest(userFacingTextGoesThroughTheCatalogue). Editora’sMessagesTest.everyLiteralKeyUsedInTheSourcesExistschecks only that every key atr("…")call names is in the base catalog, not that no literal reaches a control.
- Check (code): no source file passes a string literal in a text position: a control’s constructor,
- 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
MessageFormatpattern, 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’sMessagesTest.apostrophesInsideChoiceLimbsAreQuotedForTheRightNumberOfPasses(diagnosis.unavailablein itsmessages_fr.propertieswrites “n''''est” in a limb with{1}); Editora’s test has no such case.
- Why: a value with a placeholder is a
- 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.
- Check (code): in every catalog, a placeholder the code fills with an identifier (a line number, a port)
carries the
- INTL-11 SHOULD Technical identifiers stay untranslated: command ids, setting keys, file names and protocol
names read the same in every language. The
--helpand--versiontext 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.propertiesand its translations).
- 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 (
- 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 everychoicepattern in every catalog, is the surest evidence. - Reference: Torrenta’s
omni.targets.matchinginmessages.properties, parsed in every language byMessagesTest.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,Shiftand 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.javawrites 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 byui/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-ATcollapsed todewrites 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), orMessageFormat.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, andtr, which formats with the default locale) withMessagesTest.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’si18n/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: itsi18n/Messages.javagives the four cases (locale), sets the result as the JVM’s default where it differs (start) and formats withnew MessageFormat(value)(render); itsMessagesTest(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.
- Why:


Pauta Next · unreleased changes after 6.1.0 · Changelog · This page in the latest edition