homeassistant_espscreen/docs/TRANSLATING.md

Translating ESP Screens

Every text of ESP Screens lives in one file per language: screen_manager/translations/<code>.json. The screens, the app and the editor all read the same file. English (en.json) is the source: every other file has the same keys, and a key a language doesn't have yet shows in English.

The code is the one Home Assistant uses for the language: nl, de, fr, pt-BR, zh-Hans. A screen takes Home Assistant's language unless someone picks another one under Settings in ESP Screens; the editor follows the language of your own Home Assistant profile.

The sections

Section	Where it shows	Keep in mind
screen	On the screen itself: built into its firmware when it is installed or updated	Small screens: keep it as short as the English. One language per screen, so this costs almost no room.
addon	Messages of the ESP Screens app, and the texts it sends to the screens	Error messages are whole sentences.
editor	The ESP Screens editor in Home Assistant
_meta	The language itself	name in the language itself, english in English, plural (below), checked

screen.ha holds Home Assistant's own words (on, off, open, heating, ...). They come from Home Assistant's translations through tools/i18n.py; don't change them by hand, change them in Home Assistant's translations instead. screen.date holds day and month names and date orders from the Unicode CLDR, the same data browsers use.

The format

• Placeholders such as {n} or {name} stay exactly as they are; move them where the sentence needs them.

• Plurals are the forms of a sentence separated by |, in the order of the file's _meta.plural rule:

  Rule	Languages	Forms
  one_other	English, Dutch, German, Italian, Spanish, the Nordic languages	1 hour ago | {n} hours ago
  one_upto_1	French, Portuguese	the first form for 0 and 1
  slavic_pl	Polish	one | few (2-4, 22-24, ...) | many
  east_slavic	Russian, Ukrainian	one | few | many
  none	Chinese, Japanese, Korean	one form

• Don't use {, }, | or @ as ordinary characters.

• _meta.checked is true once someone who speaks the language has checked the whole file. The settings in ESP Screens show a language that isn't checked yet with a request for help.

Letters the screens can draw

The screens carry every letter European languages write with the Latin alphabet. A language in another script (Cyrillic, Greek, Chinese) gets its letters added only on the screens that use it, and only where they fit: a CYD has too little room for Chinese and shows English then. tools/i18n.py check says when a text uses a letter the screens can't draw.

Checking your work

python3 tools/i18n.py check

It lists missing keys, placeholders that differ from English, the wrong number of plural forms, letters the screens can't draw, and screen texts that are much longer than the English.