Translation waves: every language to daily use #

The goal is that a person can work with Exponential in their own language every day, without ever falling back to English: the administration, the extensions they use and the help. This page measures where each language stands and cuts the remaining work into waves. A wave is one language and one work set, small enough for one translator (a person or an agent) to start and finish in one sitting, at any time, independently of every other wave.

The figures and the queue below are generated from the files of this release; the rest of the page explains how a wave is done and checked. The languages, their locales and their administration translations are described in Languages in Exponential.

Contents #

1. The plan, measured: where each language stands, the help in tiers, languages without a translation, the queue
2. What the waves are
3. The order of the waves
4. Before a wave: the prerequisites
5. How each kind of wave is done
6. The checks after every wave
7. Traps
8. Done: daily use and the goal
9. Speakers and difficulty
10. Keeping this page current

The plan, measured #

Measured on 5 November 2026 by ./console exp:i18n waves from the files of this release (no database):

Where each language stands #

Percent of the strings (administration, extensions) and of the words (help), rounded down. Bold: below 97 %. "Daily-use help" is the part for editors, users and administrators (tiers).

The help in tiers #

Languages without a translation #

The languages of the shipped locales that the administration shows in English, the ones being translated on a branch, and languages of five million speakers or more that have no locale yet (the code is a proposal). Sorted by speakers per point of difficulty.

The queue: the first 60 waves #

The whole queue and the pages of a wave: ./console exp:i18n waves --list, ./console exp:i18n waves --wave=<wave>.

Made by ./console exp:i18n waves; ./console exp:i18n waves --check and the test expI18nTranslationWavesTest fail when a percentage changed or a size is more than 3 % off.

What the waves are #

A work set is a piece of the product's text that is translated as a whole:

A wave is a work set for one language, named <locale>/<work set>: ara-SA/H-help-manual-01 is the first part of the user manual in Arabic. The command shows what a wave covers and what of it is done:

./console exp:i18n waves --wave=ara-SA/H-help-manual-01    # the pages, + done, - open
./console exp:i18n waves --wave=A03                         # the contexts of part A03
./console exp:i18n waves --list                             # the whole queue

The help in tiers. The sections of the help are grouped by who needs them every day:

• Daily use: the pages of the help center (help/*.md: getting started, signing in, editing content, media, searching, shortcuts), the user manual (help/manual/), the plain-language guides (help/non-technical-people/), the administrator's how-tos (guides/) and the two books of learning (help/book-learning/, help/book-building-a-site/). These come first in every language.
• Product and audience guides: installation, the feature descriptions, and the guides for each audience of the help center (government, businesses, trainers, designers, hosting and the others).
• Developer reference: extension development, the template language and operators, backwards compatibility, standards, specifications, history and the hand-written examples.
• Tables of the generated examples: the more than two thousand reference pages are generated from the code (exp:help:examples); a language translates their tables, not the pages (see the examples).

The order of the waves #

The queue is computed, not chosen by hand. It runs in eight phases; within a phase a language with more speakers per point of difficulty comes first:

1. The catalogues of the priority group below 100 %: the administration parts and the shipped extensions of German, Arabic, Turkish, Ukrainian, Russian, Persian, Pashto and Kurdish (Kurmanji), and the Dari catalogue (fas-AF, see derived catalogues).
2. German: the daily-use help that is not translated yet (German has nearly all of the help).
3. The daily-use help of the priority group: first the setup of each language's help (S), then part after part, one language after the other: every language gets the getting-started pages before any language gets the manual. The order is Arabic (which serves the Syrian children too), Turkish, Ukrainian, Russian, Persian, Pashto, Kurdish.
4. New administration translations: the review of the derived catalogues, North Korean, then every language without a translation, the languages of five million speakers or more without a locale among them (their locale first, wave L). The languages being translated on a branch wait until it is merged.
5. The shipped extensions of every other translation below 100 %.
6. The daily-use help of every other translation, in the same way as phase 3.
7. The rest of the help of the priority group: guides, reference and tables, German first.
8. The rest of the help of every other translation.

The priority group is the most common home languages of refugee children in Hamburg: German, English, Arabic (Syrian Arabic reads Modern Standard Arabic, ara-SA), Turkish, Ukrainian, Russian, Persian (Farsi fas-IR, Dari fas-AF), Pashto and Kurdish (Kurmanji, kur-TR). Their administration is complete; what they lack is the help and some extensions, so their help comes before the new languages.

Before a wave: the prerequisites #

Read these before the first wave of a language, and again when a wave touches something new:

• share/translations/TRANSLATING.md: the rules every language shares (placeholders, markup, whitespace, what is not translated, words that need their context, the forms of the interface).
• The language's GUIDE.md next to its catalogue (share/translations/<code>/GUIDE.md): register, form of address, script and typography, and the glossary, which binds the kernel, every extension and the help. A new language writes its GUIDE.md in its first wave (A01), before the first string; a term changes in the guide first. The help uses the same glossary as the administration, so a button is named in a page as it is on screen.
• Right to left (Arabic, Persian, Pashto, Urdu, Hebrew, Yiddish, Sindhi, Uyghur, Sorani, Dhivehi, Syriac, N’Ko): the locale has TextDirection=rtl, and the help shows a language right to left when its code is in expHelpLanguage::RTL_LANGUAGES (check it in wave S; Syriac and N’Ko are not listed yet). See Right-to-left languages.
• Fonts: the administration uses the reader's system fonts; the help's PDF export embeds the font of exphelp.ini [PdfSettings] FontFiles[] (DejaVu Sans), which draws Latin, Cyrillic, Greek, Armenian, Georgian and Hebrew. For any other script, wave S adds a font that has it (a Noto font) before the first page is exported; scripts with complex shaping (Arabic, the Indic scripts, Thai, Khmer, Burmese, Tibetan) must be checked in a printed page, not only on screen. See Scripts, fonts and line breaking.
• The locale: a language needs its share/locale/<code>.ini before its catalogue can be chosen (wave L, see Adding a locale).

How each kind of wave is done #

Every wave is one branch with one commit (or a few), named after the wave (i18n-wave-ara-SA-H-help-manual-01), so that two translators do not take the same wave: look at the open branches first. Start from a current main.

Administration part (A01 to A10) #

1. ./console exp:i18n waves --wave=A03 lists the contexts of the part.
2. A new language: create share/translations/<code>/ from share/translations/untranslated/translation.ts (change the language attribute of <TS>), write GUIDE.md in A01. An existing one: refresh it with bin/linux/ezlupdate <code> (section 8 of the languages page).
3. Translate every message of the part's contexts: text in <translation>, type="unfinished" removed. Keep each <source> exactly as it is, byte for byte (see traps).
4. Measure: php bin/php/ezchecktranslation.php <code> --allow-root-user, and ./console exp:i18n waves --check names the part when its percentage changed.
5. A language that reaches 100 % in every part joins the list of tests/tests/lib/ezi18n/expTranslationQualityTest.php and the settings of a new translation (section 8).

Shipped extensions (E) #

The catalogues of ezoe, ezjscore and expimageeditor (the extensions with a catalogue in the kernel's manifest). A missing catalogue is created from the extension's translations/untranslated/translation.ts; then as above, with the extension's own context names. ezoe and ezjscore are in the quality test too.

The extensions of an installation (E1 to E6) #

The other extensions are released from their own repositories, so their catalogues are measured on an installation, not here: ./console exp:i18n fallbacks --locale=<code> lists each extension's coverage. On the reference installation (38 extensions with catalogues, 9,060 strings, measured on 26 October 2026) Croatian, Czech, Danish, Dutch, Italian, Norwegian, Polish, Portuguese (Brazil), Swedish and Turkish had 98 % of them, Spanish and Hebrew 96 %, German, Mexican Spanish, Latin and Klingon 94 %, every other translation between 28 and 35 %, Yiddish 5 %. The groups, done in this order after a language's daily-use help:

Each group is a commit in each extension's repository and a new release of that extension, with its version raised as every extension release does.

New locale (L) #

A language without share/locale/<code>.ini gets it first, as Adding a locale describes: generated from CLDR where CLDR has the language, else written by hand and checked by a speaker (most of the African languages and Haitian Creole and Guarani have no CLDR data in the generator's ICU, see Common languages still missing). Its check, expLocaleFilesTest, must pass. The code in the table Languages without a translation is a proposal: take the ISO 639-2 code the other locales use and the country with the most readers.

Derived catalogues: Dari and North Korean #

Two languages are close enough to a complete catalogue that the first wave copies it and changes only what differs. Wave L makes the catalogue usable at once; the review waves (A01 to A10, marked "review") read it part by part against the glossary.

• Dari (fas-AF, the Persian of Afghanistan): the locale exists and falls back to Iranian Persian (fas-IR). Wave L copies share/translations/fas-IR/ to fas-AF/, writes in its GUIDE.md the terms where Dari differs (vocabulary, the names of the solar months used in Afghanistan, the name of the language, دری), applies them, and removes the fallback line of fas-AF from settings/i18n.ini. A reader from Afghanistan reviews it.
• North Korean (kor-KP, Munhwaŏ, the standard of the Democratic People's Republic of Korea): a new locale derived from kor-KR. The differences are systematic, so they belong in the GUIDE.md before any string changes: no initial-sound rule (리용, 련결, 로동 where the South writes 이용, 연결, 노동); different spacing, compounds written together; the interstitial ㅅ not written; loanwords in the northern form or a native word (콤퓨터, 프로그람, 화일, 차림표 for computer, program, file, menu); the name of the language 조선말 and of the country 조선민주주의인민공화국, never the southern names; a different alphabetical order of the letters, which the locale's sorting must follow. The locale file (share/locale/kor-KP.ini, ContentLanguage=ko-KP, the North Korean won) comes from CLDR. A speaker of the northern standard reviews it.

Setting up a help language (S) #

1. Create the directory doc/<locale in lower case>/ (doc/ara-sa/) and add it to exphelp.ini [DocLanguages] Directories[] and Names[]; the name is translated in the kernel/exphelp context of the catalogues. Other locales of the language read it without a Map[] entry (ara-EG reads doc/ara-sa/).
2. Keep the English file names: a page at the same relative path needs no .paths.json. Translated file names (as German has) are possible but cost every later wave a map entry; in a script other than Latin they are not recommended.
3. Check the direction (expHelpLanguage::RTL_LANGUAGES) and the PDF font, as in the prerequisites.
4. The procedure and the settings are in Translated documentation.

Help part (H-…) #

1. ./console exp:i18n waves --wave=<locale>/<part> lists the pages of the part, - for those still open.
2. Copy each open page from doc/eng-us/ to the same path below the language's directory and translate it: the text, the headings, the link texts and the image descriptions. The front matter keys, code blocks, commands, settings, file names and anchors written in code stay as they are; the summary: is translated. Links keep their targets: a link to a page that is not translated yet shows the English page.
3. Use the glossary: a button, menu or setting is named in the page as the administration names it in that language.
4. Commit only the pages of the part: the help shows only pages git tracks.

Tables of the generated examples (X…) #

The reference pages are made by php bin/php/exphelpexamples.php from tables in doc/<language>/.examples/ (strings.json and descriptions/*.json). A wave translates the entries of its files: ./console exp:help:examples --language=<directory> --worklist=var/tmp/todo.json writes the open ones, the command then generates the pages, and --check must pass. The method is described in the examples.

The checks after every wave #

# the rules of the catalogues (placeholders, markup, whitespace, not empty, not English)
vendor/bin/phpunit --no-coverage tests/tests/lib/ezi18n/expTranslationQualityTest.php
# the finished share of a catalogue
php bin/php/ezchecktranslation.php <code> --allow-root-user
# the links and images of the help, below the part's section
./console exp:help check --below=<section>/
# the generated examples are current
php bin/php/exphelpexamples.php --check --allow-root-user
# this page: the percentages it shows are the measured ones
./console exp:i18n waves --check
# the manifest of the shipped files, before every commit
php bin/php/checkmanifest.php --fix

Then read the result in the running product: the administration with a user preference or a siteaccess Locale=<code> after clearing the translation cache (php bin/php/ezcache.php --clear-tag=i18n --allow-root-user), and the translated pages in the help center in that language. After a wave, run ./console exp:i18n waves and commit the updated page with the wave, so that the queue shows the next one.

Traps #

• A source with a Qt byte element. One source text of the administration catalogue holds an apostrophe stored as <byte value="x19"/> inside <source>. Copy every <source> element unchanged, never retype or "repair" it: the translator finds a message by its exact source, and a changed source is a new, untranslated message.
• PHP and Python count differently. A Python script that reads <source> with ElementTree's .text stops at that byte element, and one that does not skip type="vanished" or blank translations counts them as done. The figures of this page, of the languages page and of the interface language switch come from the PHP reader (expUISwitchLanguageCatalogue::messageKeys(): context, source and comment; unfinished, obsolete and empty translations not counted; percentages rounded down). When two counts disagree, the PHP one is right.
• A worktree with a linked vendor directory. In a git worktree whose vendor/ is a symbolic link to another checkout, Composer's autoloader loads that checkout's kernel classes, so the tests test the other code and still pass. Give the worktree its own vendor/composer/ and vendor/autoload.php (copies; the packages may stay links) and confirm that the test run reports tests and assertions, not "No tests executed".
• The manifest. share/filelist.md5 lists every shipped file with its checksum; the upgrade check reports every file that differs from it. Run php bin/php/checkmanifest.php --fix before each commit, after the last change.
• Placeholders and markup. %1, %name, <b>,   stay exactly; nothing is glued to a placeholder (TRANSLATING.md, rule 1). The quality test catches most of it, not all of it.
• The translation cache. A changed catalogue shows only after php bin/php/ezcache.php --clear-tag=i18n.
• Translated file names in the help need an entry in .paths.json; two translators who both add entries merge them with ./console exp:help maps --language=<directory> --fix.
• The generated part of this page is never edited by hand; ./console exp:i18n waves writes it.

Done: daily use and the goal #

• A wave is done when its work set is 100 % in that language, the checks above pass and the result has been read in the running product.
• A language is in daily use when its administration, its extensions and its daily-use help are each at least 97 %: what is left is rare enough that a reader does not meet English in a normal working day.
• The goal is 100 % in every work set, the whole help included.

Speakers and difficulty #

The speaker figures are total speakers, first and second language, in millions, rounded, after Ethnologue as Wikipedia's "List of languages by total number of speakers" and the languages' own articles give them (state of 2025). They order the queue; they are not a census, and a better figure is welcome as a change of expI18nTranslationWaves::LANGUAGES.

The difficulty (1 to 5) of a language is 1, plus 1 for a script other than Latin (2 for a script with complex shaping or without spaces between words: the Indic scripts, Thai, Lao, Khmer, Burmese, Tibetan, Ol Chiki), plus 1 for right to left, plus 1 for rich inflection or agglutination, plus 1 or 2 when little software terminology exists in the language, at most 5. The queue orders by speakers per point of difficulty.

Languages that are written in another standard are served by it and get no waves of their own: Swiss German and Bavarian (German), Neapolitan and Sicilian (Italian), the spoken varieties of Arabic (Modern Standard Arabic), Cantonese and Wu (written Chinese), the regional languages of India written in Hindi or Bengali.

Keeping this page current #

./console exp:i18n waves measures again and writes the generated part of this page and of its German translation; it keeps the date while nothing changes. This page itself is not counted among the help's pages. ./console exp:i18n waves --check and the test tests/tests/kernel/classes/i18n/expI18nTranslationWavesTest.php (no database) fail when a percentage of a language changed, a language without a translation was added or got one, or a size is more than 3 % away from the measured one, so that a small edit of a help page does not make every other change fail, while the plan cannot go stale.