Messages and translation

Required

• Ship a default text for every message

  LOC-25

  Every message key has a text in the default language, and a missing translation falls back to it key by key at run time. A missing text never stops a screen from loading.

Recommended

• Translate whole sentences

  LOC-13

  On sites with several languages, or one planned, keep every visible text in a message file. Use one entry per whole sentence with named placeholders, and never build a sentence from translated pieces.

• Get plurals right in every language

  LOC-12

  Choose plural forms from the language's plural rules instead of adding an "s".

• Choose gender and other variants inside the message

  LOC-24

  When a sentence changes with a person's gender, a role or another fixed choice, put every variant in one message with a select argument. Never pass a translated word into a placeholder.

• Extract messages from the code with a tool

  LOC-18

  Build the source message file from the code with an extraction tool, never by hand. CI fails when the committed file differs from a fresh extraction.

• Fail the build on missing or broken translations

  LOC-19

  Before release, every key in the source exists in each published language, and every translation has the same placeholders as its source.

• Mark translations stale when the source changes

  LOC-20

  When a source sentence changes, mark its translations as needing review in every language. A stale translation is never published as current.

• Give translators context and a review step

  LOC-21

  Every message carries a note for translators, and every translation, human or machine, is reviewed by a fluent speaker before release.