本页尚未翻译,目前显示英文。
Translating
RadioFoundry has two sets of text to translate: the radio's (firmware) and the web site's (flasher, Codeplug Editor, tools). They are separate catalogs with separate tools; a language can have one without the other. English is the source of both. This page is the how-to; the rules are in ui.md 2.5 (radio) and website.md, Translating (site).
| Radio | Web site | |
|---|---|---|
| Catalog | core/ui/lang/<code>.po (gettext) |
site/i18n/<code>.json (flat JSON) |
| Language list | The catalogs that exist | site/i18n/languages.json |
| Tool | tools/i18n.py |
python3 -m rfoundrysite.i18n (from site/) |
| Build switch | CONFIG_LANG_<CODE>, one per language; CONFIG_LANG_DEFAULT_<CODE> to start in it |
None: every language is on the site |
| Missing string | Shown in English; fails CI | Shown in English; fails CI |
| Characters | ASCII and Latin-1 (U+00A0 to U+00FF) | Any Unicode |
Translating the radio
How it works
The source is English. A string the radio shows is marked where it is written, with a key that names it and its English:
| Mark | Where | Meaning |
|---|---|---|
TR(KEY, "Text") |
In code | Returns the text in the language in use |
TRN(KEY, "Text") |
Where the text is stored now and shown later: an initializer of a static const array or struct, a field, an event |
A tr_id_t for the text (a name for it, not the text); the code that shows it calls tr() on it |
TRX(KEY, "Text") |
In the same places, for text never translated ("RX", "12.5 kHz") that sits beside translated text |
A tr_id_t like TRN; no catalog has it |
tr(id) |
Where a table entry is shown | The text in the language in use; the English when there is no translation |
tr_en(id) |
Where the English is needed too (Find matches both) | The English |
ui_toast(TR(ZONE_TOAST_FULL, "Zone full")); // shown right here: TR gives the text
static const tr_id_t modes[] = { TRN(VALUE_OFF, "Off"), TRN(VALUE_AUTO, "Auto"), TRX(WORD_VOX, "VOX") };
sb_str(&b, tr(modes[i])); // stored first, shown later: TRN or TRX, then tr()
TR cannot be used in a static const initializer: it is a function call, and which language is in use is known only
when the text is shown. That is what TRN is for. TRX exists because every entry of such an array is a tr_id_t,
so text that is never translated needs one too.
The key is a C identifier, upper case. One key always has the same English (the tool fails otherwise); the same English
may have more than one key, where it needs different translations. The English at the mark is the source of truth: a
catalog entry is the key's (its msgctxt), and the tool reads the English from the mark.
Key names
A key says where the text is shown and what it is for, not what the English says: AREA_ROLE_MEANING
(ZONE_TOAST_RENAMED, CHAN_LABEL_BANDWIDTH, DENY_FIX_ADD_CODEC). The English can then change without the name
going stale, and a translator who reads the key in a catalog knows what kind of text it is.
| Part | What it is |
|---|---|
| Area | The screen or feature the text belongs to, as in the code: HOME, ZONE, CHAN, MSG, SHARE, QUICK, SET, DUAL, APRS, ROAM, ... Reuse one from the catalogs before making a new one. Left out for text several areas share (VALUE_OFF, HINT_OK_PICK_BACK, WHY_SCAN_NOT_IN_BUILD) |
| Role | How the text is shown, from the list below |
| Meaning | What it says, in a few words. Left out when the area has one such text (QUICK_TITLE, GPS_HINT) |
| Role | The text is |
|---|---|
TITLE |
A screen's title; also on the row that opens that screen |
ROW |
A list row that does something when picked: an action, a choice, a sub-menu |
LABEL |
The name beside a value: a settings row, a field, a caption |
VALUE |
A value shown for a setting or field |
HINT |
The hint row: what the keys do |
TOAST |
A short message after a key press |
BANNER |
A line of a banner (an event from outside) |
BODY |
Running text on a page, or a piece of it |
STATE |
A status word a screen shows while something goes on (TALKING) |
CHIP |
A short tag: the status bar, a list row's right edge |
EMPTY |
What a list or page shows when it has nothing |
WHY |
Why something can't be done: a refusal, a missing feature |
FIX |
What to do about it |
ASK |
A question to confirm |
ERR |
A failure reported by a background job |
UNIT |
A unit joined to a number ( channels) |
PART |
A piece joined to other text, with no role of its own (of) |
WORD |
A term used as title, label and value alike (VFO, Scan) |
A piece of a sentence ("Message from ") takes the role of the sentence. A number in a name is the number in the
text (VALUE_10_MIN, HINT_1_5_PICK_BACK), never a counter: two texts that would get the same name differ in
meaning, so say how.
A tr_id_t is opaque. Code passes it to tr() or tr_en(), or compares it with TR_NONE (none: zero, so a field
left out of an initializer is none), and nothing else. With a language built it is the key's number (TR_<KEY> in
the generated tr_keys.h), and tr() reads it from a table: no search. With every language switched off it is the
English text itself and costs nothing. Code compiles the same either way.
tools/i18n.py reads the marks, keeps the catalogs in step and turns them into the tables the build links in: the
English of every key, and each language's translations by key.
Adding a language
-
Start the catalog:
python3 tools/i18n.py --new <code> <name>.<code>is the ISO 639-1 code (fr),<name>the language's own name (Français). This writescore/ui/lang/<code>.powith every marked string, untranslated. A CJK language adds its Latin name:python3 tools/i18n.py --new zh 中文 Chinese(below). -
Add the build switches:
CONFIG_LANG_FRbuilds the language in,CONFIG_LANG_DEFAULT_FRmakes it the one the radio starts in (forfr):File Change config/features.mkCONFIG_LANG_FR ?= nandCONFIG_LANG_DEFAULT_FR ?= n, next to the others; both inFEATURES; the$(error CONFIG_LANG_DEFAULT_FR=y needs CONFIG_LANG_FR=y)line, as the other languages havecore/config.hThe #ifndefdefaults (0) of both, andCONFIG_LANG_FRadded toCONFIG_LANG_ANYdocs/build-config.mdA row for each in the user interface table docs/feature-matrix.mdA row for each in the user interface table, with the measured bytes (the default costs none) tests/hil/features.toml[feature.lang_fr],switch = "LANG_FR", and[feature.lang_default_fr],switch = "LANG_DEFAULT_FR"python3 tools/boards.py docsthen adds the switches to the generated tables of the feature matrix.tools/i18n.py --checkfails until every one of these is there. -
Translate (below), then run
python3 tools/i18n.py --checkand the host tests (make -C tests/host). -
Look at it: build the gallery in your language (below), or flash a build and pick it in Settings > Display > Language.
A new language is off by default. It is turned on by default only when it is widely used and the radios have the
flash for it (build-config.md): Spanish is, Italian isn't. A language that is off is still listed on the
radio, dimmed, and the web flasher offers to turn it on for a visitor whose browser asks for it. The web flasher also
asks which language the radio starts in (preset to the page's when the build has it) and sets
CONFIG_LANG_DEFAULT_<CODE> from it. A language picked there is built in: its CONFIG_LANG_<CODE> goes on with it.
Translating the catalog
Each entry is the English (msgid) and its translation (msgstr). Fill in the empty msgstr lines with any .po
editor (Poedit, Lokalize) or a text editor. An empty one shows the English, so the radio works with a catalog partly
done, but CI fails until every string is translated (When the source changes). In a text
editor, write a double quote inside a string as \", as the msgid does.
#: core/ui/ui_menus.c
msgid "Backlight"
msgstr "Retroiluminación"
| Rule | Why |
|---|---|
| Keep it short. Most screens are 128 or 160 pixels wide: about 21 characters in the small font, 16 in the list font | A row too long is cut with an ellipsis; a toast or hint is cut |
| Keep leading and trailing spaces, and the colon at the end | The code glues a number or a name to the text: "Volume " + "5" |
Keep {a|b} groups as groups, with the same number of choices |
A text alternate: the radio shows the first choice that fits, longest first. Write each choice shorter than the one before |
Use only ASCII and Latin-1 letters (á é í ó ú ñ ü ç ß ...) and … · → ° ⤒ ⤓ |
The radio draws one byte a character; --check rejects anything else. A CJK catalog is the exception, and says so (below) |
Start every hint group that names the Back key with exactly your translation of "Back" |
Hints keep the Back group at the right edge by matching that word: change it and every Back group must change with it |
| Status strip words (IDLE, NO TX, SCAN, DUAL, ROAM) and chips (Lock, DMon, Priv) no longer than the English; keep the English when nothing fits | They sit in fixed slots of the status strip |
| Don't translate the standard abbreviations the source leaves unmarked (TG, TS, CC, RX, TX, VFO, DMR, FM) | Radio operators know them; they aren't in the catalog |
Some strings are joined in English word order, a number or name before or after a piece of text ("14m" + " ago").
Translate the piece so the joined text reads well ("14m atrás"), even when the usual phrase puts the words the other
way round.
To see where a string goes, search for its key (the msgctxt line) in the file its #: line names: grep -n 'BACKLIGHT,' core/ui/ui_menus.c. The comments next to a TR() often say more. A string with a leading or trailing space is
always such a piece.
Chinese and other CJK languages
The Latin fonts have no glyph for Chinese, so such a catalog is UTF-8 and brings its own face. Everything else works as above: one catalog, one switch, the same checks.
| Step | What |
|---|---|
| The catalog | tools/i18n.py --new zh 中文 Chinese writes it with an X-Glyphs: utf8 header and an X-Language-Name-Latin one. A catalog with that header holds UTF-8: ASCII, font.h's glyphs, and characters the CJK face has. Two-byte characters (Latin-1 letters with an accent) are not allowed: the text layer decodes only three-byte sequences, so that Latin-1 names, messages and the Spanish catalog keep working in a build with the CJK face. --check lists every character it rejects or the face lacks |
| The list | A build without the CJK face (CONFIG_LANG_ZH off) still lists the language, dimmed: it shows X-Language-Name-Latin ("Chinese"), because the Latin font would draw the UTF-8 name as boxes |
| The face | tools/cjkfont.py rasterizes every character the catalogs use into a 16x16 one-bit glyph and writes the table the firmware links. 480 characters are 15.4 KB; with the text, Chinese costs 32,856 bytes. Run it whenever a translation adds a character (--check fails until it does) and commit both |
| The font | One whose license allows embedding bitmaps: an SIL OFL font such as Noto Sans CJK SC or Source Han Sans. The generated file carries the font's copyright, its full OFL text and the font file's SHA-256, because that data is under the font's license, not MIT (see the header of core/ui/cjk_font_data.c). Do not use a vendor font that forbids it |
| Size | A CJK character is 16 px wide and 16 tall, the height of the 8x16 font: 8 characters a line on a 128 px screen, 10 on a 160 px one, 15 on a 240 px one. A line must be at least 16 px high. A 240 px color radio draws its words in 8x16 (a CJK build moves its text pages up to that font too) and shows Chinese everywhere; a layout whose words use the 5x8 or 6x12 font (a 128x64 display, and the 160x128 class) has no room for 16 px lines, so those boards list LANG_ZH and LANG_DEFAULT_ZH in BOARD_UNSUPPORTED, and CI's maximal build and the flasher leave the language out there |
| Cutting | A string too long for its space is cut at the end, whole characters only (gfx_text_fit_end for a line that keeps its start, gfx_text_fit for a middle cut), because Chinese has no spaces to cut at a middle. A line wraps after any CJK character (wrap_line); Latin words inside it still wrap at their spaces |
| Switch | CONFIG_LANG_ZH is off by default. Measure it like any switch and put the bytes in the feature matrix |
The table in this tree comes from Noto Sans CJK SC 2.004 (noto-cjk), rendered with Pillow 12.1. Rebuild it with:
python3 tools/cjkfont.py --font NotoSansCJK-Regular.ttc --font-index 2 --weight 0 \
--font-name "Noto Sans CJK SC 2.004 (NotoSansCJK-Regular.ttc, index 2)" \
--copyright "2014-2021 Adobe (http://www.adobe.com/), with Reserved Font Name 'Source'." \
--license LICENSES/OFL-1.1.txt --spdx OFL-1.1 \
--po core/ui/lang/zh.po --out-c core/ui/cjk_font_data.c --out-png /tmp/cjk.png
--font-index 2 picks the Simplified Chinese face of a .ttc (0 is Japanese). The header records the font file's
SHA-256: a different hash means a different font file, so say which one you used in the pull request. --weight picks
a variable font's axis; 0 keeps a static face's own weight. A different Pillow can render slightly different bytes;
commit the table it wrote.
When the source changes
python3 tools/i18n.py --sync adds the new keys to every catalog (untranslated) and drops the ones the source no
longer has. A change that adds or edits a marked string runs it and commits the catalogs with the code.
| Case | What --sync does |
CI |
|---|---|---|
| A new key | Adds it untranslated | Fails until it is translated in every catalog |
| A key's English edited | Keeps the translation, still in use | A warning on the pull request: the old and new English and each language's text |
A translation marked #, fuzzy by a translator (in doubt) |
Kept, not used | Fails until a translator checks it and removes #, fuzzy (and the #| line under it) |
| New English under a new key | A new entry, untranslated; the old key dropped | Fails until it is translated |
An entry follows its key, so an edit of the English never loses a translation. A small edit often leaves the
translations right, so a key whose English changed while a translation stayed the same is a warning on the pull
request, not a failure (tools/i18n_changes.py): the old and new English and each language's text. Say in the pull
request whether each language still fits. When the meaning changes, use a new key: its entry starts untranslated.
Renaming a key
The tool matches a catalog entry by its key alone, so a key renamed only at the mark looks like a new key: --sync
drops the old entry with its translations and adds an empty one. Rename with the tool, which changes the marks and
the catalogs together:
python3 tools/i18n.py --rename OLD_KEY NEW_KEY # one key
python3 tools/i18n.py --rename names.txt # many: a line "OLD_KEY NEW_KEY" each
python3 tools/i18n.py --sync
It rewrites the key at every mark in core/, tests/ and sim/ and the msgctxt of its entry in every catalog,
and refuses a name that is taken. The pairs of a file are renamed together, so two keys may swap names. Afterwards
git diff core/ui/lang shows only msgctxt lines; no msgstr is lost.
The site's catalogs follow the same rule for edited English: a key whose English changed while a translation didn't is a warning.
A pull request that adds or rewrites text and can't translate it lists it as an open task in its description
(- [ ] translations: es, it), and the strings are translated before the merge. To build or test with strings still
untranslated, python3 tools/i18n.py --check --allow-pending skips them; CI doesn't.
python3 tools/i18n.py --stats shows how much of each catalog is translated.
Marking text in new code
| Text | Mark |
|---|---|
| A word or sentence the user reads | TR(KEY, "..."), or TRN(KEY, "...") in a table and tr() where it is shown |
| A screen's title, hint, empty text, a menu row | TRN() in the table: list_draw and the menus translate them |
| A hint built when the screen is drawn | SF_HINT_FN and hint_fn in the screen's definition, returning text already in the language in use |
| Names, numbers, units, standard abbreviations | Not marked; in a table of tr_id_t beside marked text, TRX(KEY, "...") |
| Debug link names and values, protocol text sent off the radio, log text | Not marked: tools and tests read them |
| Canned text messages | Marked: the radio sends them in the language in use, so keep them short and plain |
| Search words (the second string of a settings row) | Not marked: Find matches the English words and the shown name |
A mark's text is one C literal, or literals and the font.h glyph macros (GLYPH_ELLIPSIS, TEXT_ALT_OPEN, ...)
next to each other. Not a variable, no \n (write the line break with sb_chr). A macro whose value is a
TRN(...) is found like any other. Name a new key by Key names; a key in use is reused for the
same text where the meaning is the same. TR_<KEY> must not be a name the source already uses (the tool says so). python3 tools/i18n.py --rewrite [FILE]
gives a mark written without a key, TR("..."), one made from its English (the same English gets the key it already
has); rename it before the commit (--rename, below).
A text that travels between tasks (an event) travels as its tr_id_t, not as text. Build text from pieces
with sbuf_t, not strcpy/strcat: a translation can be longer than the English, and str_copy and sb_str
cut it safely. Don't compare shown text with strcmp; compare the state it came from. After marking, run
--sync and commit the catalogs.
Looking at the result
make -C tests/host ui-gallery renders the screens in English. To see a language, build the simulator with that
language in (UI_LANG on the make line turns its CONFIG_LANG_<CODE> on, for a language that is off by default),
then render the gallery with UI_LANG set to its code, into a directory outside the repo, and look for text that is cut
or runs into something:
make -C tests/host -B uiSim UI_LANG=fr
cd tests/host && UI_LANG=fr ./uiSim --gallery /tmp/gallery-fr # contact sheets in /tmp/gallery-fr/sheets
Commit only the English gallery.
Flash cost
The first language costs the most: the lookup, the English of every key in one table (the literals it replaces, plus an offset per 8 keys) and the Latin-1 glyphs of every font. Each further language adds only its text, about the size of the catalog's translations, and an offset per 8 keys. Measure a language like any switch (building.md) and put the bytes in the feature matrix.
Translating the web site
- Copy
site/i18n/en.jsontosite/i18n/<code>.jsonand translate the values. Keep its format (one space of indent, UTF-8 as is:json.dumps(data, ensure_ascii=False, indent=1)). A key left out shows the English, but CI fails until every key is there (python3 -m rfoundrysite.i18nfromsite/lists them). - Add the language to
site/i18n/languages.json(code,name,dir,locale), and its catalog totools/generic_allow.txtnext toen.json: it carries the same per-radio texts. - If its plural rule differs from English's, add it to
PLURAL_RULESinsite/rfoundrysite/i18n.py. python3 site/build.py --strictchecks the catalog.python3 site/build.py --serveandhttp://localhost:8000/<code>/shows it.
| Rule | Why |
|---|---|
Keep {name} placeholders and HTML tags exactly, and anything else in angle brackets (<radio address>) |
The check fails otherwise; the page fills them in |
Plural keys (key.one, key.other, ...): give your language's forms. Most European languages need .one and .other; PLURAL_RULES lists the others |
Picked by the count; .other is the fallback |
| Keep product and protocol names (RadioFoundry, DMR, DFU, CPS) and radio model names | They are names |
What the site leaves in English (radio data, error details, logs) is listed in
website.md, What stays English. Translated documentation pages go in
docs/i18n/<code>/.
Checks
| Check | Runs |
|---|---|
python3 tools/i18n.py --check |
Every mark has a key, one English per key; catalogs in step with the source, none untranslated or fuzzy, drawable characters, text alternates, spaces, the switch in every file |
python3 tools/i18n_test.py |
The tool: keys, tables, sync, migration, rewrite, rename |
make -C tests/host |
i18nTest: a key to its translation or its English, tr_en, switching, a language not built; uiFlowTest: the Language screen |
python3 site/build.py --strict |
The site catalogs: keys, placeholders, tags, languages.json |
python3 -m rfoundrysite.i18n (from site/) |
The same, and no key missing from a language |
tools/i18n_changes.py |
Warnings, not failures: English the branch changed while a translation didn't, radio and site |
tools/ci.sh runs all of them. In a pull request the warnings show as annotations on the changed catalog lines.