Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · App internals

Localisation

On this page
  1. Supported languages
  2. Choosing the language
  3. How texts are organised
  4. Texts shown by Rust
  5. Right to left
  6. Question format keywords
  7. Adding a language
  8. Translation style

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#

TagLanguageOwn nameDirectionIntl locale
deGermanDeutschleft to rightde-DE
enEnglishEnglishleft to righten-GB
zh-HansChinese (Simplified)中文(简体)left to rightzh-Hans-CN
hiHindiहिन्दीleft to righthi-IN
esSpanishEspañolleft to rightes-ES
arArabicالعربيةright to leftar

German is the reference shape of the catalogue; English is the fallback.

Choosing the language#

  • The setting is System or one of the tags above. It is stored in settings.json (language) and therefore part of the settings export and import (see settings-backup.md). The frontend mirrors it in localStorage because the texts are needed before settings.json arrives.
  • System walks navigator.languages and takes the first supported language. Regional variants map to their language: es-MX → es, zh-CN, zh-SG and zh-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>.ts holds German and English for one area of the app (shell, questions, dashboard, detail, settings, filter, permissions, native, support). src/i18n/catalogue.ts lists the namespaces.
  • src/i18n/locales/<tag>.ts holds one further language for all namespaces. Its type is Translation, 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.PluralRules picks the entry. Arabic uses all six, Chinese only other.
  • 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), never left/right.
  • Horizontal motion multiplies by var(--dir-sign) (1 or -1).
  • Icons that point along the reading direction (back, chevron) are listed in DIRECTIONAL in src/ui/Icon.tsx and mirrored by src/ui/Icon.css.
  • Repository names, issue numbers, code and URLs stay left to right inside the text; wrap them in <bdi> or set dir="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#

  1. Add the tag to LANGS in src/i18n/define.ts (the order is the order of the picker).
  2. Add its Intl locale to LOCALES and its own name to ENDONYMS in src/i18n/index.ts. If the language is written right to left, extend direction.
  3. Map regional variants in matchLang if the base tag alone is not enough (as for Chinese).
  4. Create src/i18n/locales/<tag>.ts with export const <name>: Translation, translating every key. Give each plural the categories the language needs. Keep every {placeholder} and keep question-format keywords German.
  5. Register it in tables in src/i18n/index.ts and in the language union in src/core/types.ts.
  6. Add the variant to Language in crates/core/src/store/settings.rs (with a serde rename if the tag is not plain lowercase) and extend its test.
  7. Add the tag to SAME_AS_ENGLISH in src/i18n/i18n.test.ts with the keys that are intentionally identical to English (brand names, hosts).
  8. 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.

Docs version: dev