For developers · App internals
Localisation
On this page
Gitoodo shows every text in one language, chosen in Settings → General → Language. The window, the tray menu and tooltip, system notifications, user-facing errors and chat webhook messages always follow the same language and switch together at runtime, without a restart.
Supported languages#
| Tag | Language | Own name | Direction | Intl locale |
|---|---|---|---|---|
de | German | Deutsch | left to right | de-DE |
en | English | English | left to right | en-GB |
zh-Hans | Chinese (Simplified) | 中文(简体) | left to right | zh-Hans-CN |
hi | Hindi | हिन्दी | left to right | hi-IN |
es | Spanish | Español | left to right | es-ES |
ar | Arabic | العربية | right to left | ar |
German is the reference shape of the catalogue; English is the fallback.
Choosing the language#
- The setting is
Systemor one of the tags above. It is stored insettings.json(language) and therefore part of the settings export and import (seesettings-backup.md). The frontend mirrors it inlocalStoragebecause the texts are needed beforesettings.jsonarrives. Systemwalksnavigator.languagesand takes the first supported language. Regional variants map to their language:es-MX→es,zh-CN,zh-SGandzh-Hans→zh-Hans,ar-EG→ar,de-AT→de,hi-IN→hi. Traditional Chinese (zh-Hant,zh-TW,zh-HK,zh-MO) and every other language fall back to English.- The picker shows each language in its own name, regardless of the current language.
How texts are organised#
src/i18n/<namespace>.tsholds German and English for one area of the app (shell,questions,dashboard,detail,settings,filter,permissions,native,support).src/i18n/catalogue.tslists the namespaces.src/i18n/locales/<tag>.tsholds one further language for all namespaces. Its type isTranslation, so a missing or extra key is a compile error.t("namespace.key", vars)returns a text;{name}marks a variable. Numbers passed as variables are formatted in the digits of the language.tp("namespace.key", count, vars)returns a plural text. A plural is an object with one entry per CLDR plural category the language uses (zero,one,two,few,many,other);Intl.PluralRulespicks the entry. Arabic uses all six, Chinese onlyother.- Dates, times, relative ages and numbers go through
Intl(formatDate,formatDateTime,formatAge,formatNumber). Never build them by hand.
Texts shown by Rust#
The native namespace holds the texts of the tray menu and tooltip, system
notifications and chat webhook messages. The frontend resolves them in the current
language and sends them with the language's digits to the set_ui_texts command
at start and on every language change (src/App.tsx). Rust rebuilds the tray menu
right away and fills the placeholders itself. Until the first push, English
applies. User-facing errors reach the frontend as categories and are translated
there.
Right to left#
Arabic sets dir="rtl" and lang on the root element. To keep the layout
correct in both directions:
- Use logical CSS properties (
margin-inline-start,padding-inline-end,inset-inline-start,text-align: start,border-inline-start), neverleft/right. - Horizontal motion multiplies by
var(--dir-sign)(1or-1). - Icons that point along the reading direction (
back,chevron) are listed inDIRECTIONALinsrc/ui/Icon.tsxand mirrored bysrc/ui/Icon.css. - Repository names, issue numbers, code and URLs stay left to right inside the
text; wrap them in
<bdi>or setdir="ltr"where they stand alone.
Question format keywords#
The keywords of the question format (Empfehlung, Frist, ja/nein and the
others in question-format.md) are part of the machine-readable format and stay
German in every language. Only their explanations in the UI are translated.
Adding a language#
- Add the tag to
LANGSinsrc/i18n/define.ts(the order is the order of the picker). - Add its Intl locale to
LOCALESand its own name toENDONYMSinsrc/i18n/index.ts. If the language is written right to left, extenddirection. - Map regional variants in
matchLangif the base tag alone is not enough (as for Chinese). - Create
src/i18n/locales/<tag>.tswithexport const <name>: Translation, translating every key. Give each plural the categories the language needs. Keep every{placeholder}and keep question-format keywords German. - Register it in
tablesinsrc/i18n/index.tsand in the language union insrc/core/types.ts. - Add the variant to
Languageincrates/core/src/store/settings.rs(with aserderename if the tag is not plain lowercase) and extend its test. - Add the tag to
SAME_AS_ENGLISHinsrc/i18n/i18n.test.tswith the keys that are intentionally identical to English (brand names, hosts). - Run
npm test: the guard checks key parity, plural categories, placeholders and untranslated values. Then check the layout in the real app at 400 px width for clipped labels.
Translation style#
Natural and concise, as a native speaker would write a UI; no word-by-word translation. Labels must fit the 400 px window. Product name "Gitoodo" and forge names (GitHub, GitLab, Gitea, Forgejo) are never translated.