Skip to content

Admin console — translating the web UI

The staff console at / can be served in more than one language. This page is the whole workflow: how to extract, how to add a language, how to compile, and what a translator touches.

The migration proceeds in slices, in this order: the login page and the shell, the dashboard and the list pages (Servers, Nodes, Instances, Players), the per-server page and its tabs (Overview, Players, Missions, Log, Events, Configuration), the write dialogs (the one confirm.html component every write in the console opens) and the row buttons and the console's JavaScript, and the top bar's breadcrumb (which also wrapped its group word and reused each page's own label rather than duplicating it) are wrapped. The tail is closed too: the tab strip's problem tooltip (a sentence RECORD rendered through the guarded say) and the shell's two standalone error documents (refusal_page / retryable_page, whole pages composed in Python and translated at render). Every visible string in the console is wrapped — including the two tab strips' aria-label attributes (_state.html "Cluster", server_detail.html "Server"), which reuse the pages' own labels rather than adding a second msgid — so a language pack added later finds nothing left unwrapped. The Settings page's generator chrome is wrapped too: the control kind words (services/webservice/configgen.KIND_LABELS), the default / required / validate on save markers, the restart banner and the Add/Add-entry labels are i18n._-marked and filled in every catalog. The three strings that mark a cross-file include: are wrapped too — the included: <file> badge, the sentence that a save writes the included block into THIS file (never into the schema it is described by), and the include cycle: notice — and filled them in every catalog too. Its schema KEYS are a different thing and are deliberately not translated — see below. Wrapping a string is invisible until a translation exists (English is the msgid), so the tree stays green while the work proceeds.

What is deliberately NOT wrapped: the action's own message, and the plain-text refusal bodies.

An action's own message (its success, its typed refusal) is composed where the action runs and is shown on both the web console and the Discord side. Making it language-dependent would leak one surface's language into the other — the same class of bug the leak test exists to catch — so it stays English. The one-shot notice that carries it therefore looks its message up in a catalog only when the message is the console's OWN (notice.refusal, set by pages/actions._refusal_notice); an action's message is rendered verbatim (_notice.html), so it can never be translated into one surface alone.

The console's own refusals are a different thing and ARE wrapped: the 403 wording a write route composes before any action runs (pages.dashboard.out_of_scope_refusal, pages.actions. REFUSAL_OUT_OF_SCOPE / REFUSAL_NO_IDENTITY / REFUSAL_CONFIRM_REQUIRED) and the contradictory-form refusals a launch route composes from the fields it parsed itself (pages.actions.REFUSAL_WEATHER_CONFLICT / REFUSAL_WEATHER_NEEDS_EXTENSIONS). Nothing here is composed where a write runs or shown on Discord, so translating it leaks nothing. These reach the page through the one-shot notice (_notice.html's notice-msg, the notice target shell.js swaps in): the SERVER renders the sentence in the request's language and the JavaScript only swaps it in.

A refusal a route shares with an action. When the action ALSO guards the same condition — because direct, REST and MCP callers never go through the route — the route raises its own wrapped copy and the action keeps its unwrapped sentence as the backstop. Only the route knows the request's language, so only its copy can be translated; the action's message has no request to resolve against and stays English for the surfaces that share it. The two must state the SAME condition from ONE predicate, never a second copy of the boolean (the launch routes reach the mission plugin's states_unapplied_weather rather than re-stating it), or the operator meets a launch one surface refuses and the other greys on.

The plain-text DOWNLOAD refusal bodies (pages/server_detail._refuse / _log_refuse — the mission and log downloads — and pages/nodes._refuse — the node-log download, the plain-text refusal body at pages/nodes.py:194) stay English on purpose: a download has no page to render its failure into, so the sentence IS the answer, and the same body is what the download's caller reads. They are a narrow, documented exception rather than a gap — do not "fix" them by translating them.

The operator data — server, mission, player and coalition names, and the node's own name — is likewise never translated: the console shows a translated label beside a name that stays exactly as the operator typed it.

The schema KEYS on the Settings page are the same rule one level down: the pykwalify schemas carry identifiers, not prose, so a field's label is its key (guild_id, database.pool_min, logging.loglevel) and stays English in every language — translating a key would break the link between the page and the file it writes. The generator's own chrome words ARE wrapped (see above); the keys are not, and do not "fix" them by adding them to a catalog.

The machinery is in services/webservice/i18n.py; the extraction config is services/webservice/babel.cfg.

How a string becomes translatable

  • In a template, wrap it with Jinja's own translation tag: {% trans %}Sign in{% endtrans %}.
  • In the console's Python (services/webservice/**/*.py), wrap it with the _() marker: CONTROL_LABEL = i18n._("Sign in with Discord"). The marker returns the string unchanged — the real translation happens where it is rendered, by the template environment, which is built per language.

English is the msgid. A wrapped string that has no translation is a no-op: it renders exactly as before. That is what lets the console be translated one slice at a time without any visual change until a catalog exists.

The console keeps its own gettext domain, webui, so the frontend's strings never mix with the bot's Discord strings (the two share almost nothing). The catalogs live in the bot's existing tree: locale/<lang>/LC_MESSAGES/webui.po (source) and webui.mo (compiled, what runs).

The row buttons: translate, then interpolate

A row control's tooltip and accessible name name the TARGET ("Restart server SRS-1"), and a server name is operator data that must never be translated. So those strings are wrapped as their English TEMPLATE (with a {server} / {node} / {player} hole) and rendered through the environment's ONE guarded global say (templating.SENTENCE_GLOBAL): the template is translated FIRST, the target interpolated AFTER. A translation that omits a hole degrades to the English sentence rather than taking the row down (templates/_strip.html, templates/_table.html). A control's plain strings besides its names — its menu label, its hint, a field's label/help — are rendered with the environment's _(…). The declarations in pages/actions.py are where a control's copy is marked.

The console's JavaScript: a served message map

The static JS under services/webservice/static/ carries no user-visible string and no translation logic. Instead the server renders the strings for the REQUEST's language on a gated route — /i18n/messages.js (i18n.MESSAGES_PATH, declared dashboard.view like the console's own pages, so it respects the access gate exactly as they do) — as window.DCSSB_MESSAGES plus ONE substitution helper, window.dcssbMsg(key, params). The scripts look a key up and swap a {name} hole; they never translate. base.html includes the map before the scripts that read it. The map is the SAME webui catalog the pages use (its keys are i18n.JS_MESSAGES), so a page and its scripts can never disagree about the language — and adding a string to the JS is adding a key there, never a JS edit. The route is served no-store: a language-shaped body must never sit in a shared cache.

A JSON endpoint whose strings the JS shows rather than looks up needs no key at all. The SERVER renders the sentence for the request's language and the script swaps the finished string into the DOM. The log window (pages/server_detail.py) works this way: each message its JSON body carries is a sentence record — an i18n._-marked English template plus its operator data — rendered through the SAME guarded say the write dialogs use (templating.SENTENCE_GLOBAL, on the request's per-language environment). The template is translated FIRST and the data interpolated AFTER, so a node name, a log path or an error type stays exactly as the operator's; a bad catalog line degrades to English rather than taking the log view down. The tab's own initial render goes through the same call, so the first paint and every follow agree on the language. None of this lives in the JavaScript.

The standalone error documents

Two whole pages are composed in Python, not from a template: shell.refusal_page (the 403 a browser is refused with) and shell.retryable_page (the 503 a browser gets while a just-restarted bot verifies its identity). They are deliberately standalone — an error page must not depend on the shell it renders instead of — so they have no Jinja render step to install a language for.

Their copy is therefore translated at render through the request's own per-language environment (shell._page_language_and_translator → i18n.environment_for): the environment's installed translations object, exactly as a template uses it. The Python i18n._ on each literal is the extraction marker only (it returns the string unchanged); the real translation is the environment's, resolved per request. The language code is carried into the document's lang attribute, and the retry page's own JS status lines are translated too — emitted through json.dumps(..., ensure_ascii=False) so a translation can never break the script literal. With no request context (the string builders called directly), both default to the source language, so the English document is byte-for-byte what it was.

The tab strip's problem tooltip is the same rule in template form: pages/dashboard._tab_problem returns a sentence RECORD (the English msgid with a {count} hole), and _state.html renders it through the guarded say — translated first, the count interpolated after — so the tooltip follows the reader's language and a bad catalog line degrades to English rather than taking the page down.

Extract, insert, compile

Babel is a build/developer tool — the console at runtime uses only the standard library's gettext. It is declared as a build/test tool in requirements.in (babel==2.17.0); to run the extraction (or the suite) on a machine without the bot's environment, install it with pip install babel. Run these from the repository root:

# 1. pull every translatable string out of the templates and the page code
pybabel extract -F services/webservice/babel.cfg -o /tmp/webui.pot \
    --project=DCSServerBot --copyright-holder=DCSServerBot --no-wrap .

# 2. insert the NEW entries from /tmp/webui.pot into each catalog BY HAND, in that
#    file's own existing style — every existing entry stays byte-identical.

# 3. compile the .po sources to the .mo files gettext reads
pybabel compile -d locale -D webui

tests/test_webui_i18n.py::test_every_wrapped_string_is_in_the_shipped_catalogs runs the extraction and fails if a template or a page string is not in the catalogs — so extraction and templates cannot drift.

A correct catalog diff is pure additions — new #: / msgid / msgstr blocks only, no existing entry reflowed or re-wrapped and the header untouched. A diff of thousands of lines, entries that move, or a new #, fuzzy entry is drift: restore the file and redo the insert by hand.

Do not run pybabel update over the catalogs — it does not reproduce them. The committed catalogs are hand-maintained: their wrapping follows no width pybabel update writes, so an update rewrites the whole file and buries the handful of genuinely new strings in thousands of changed lines. Measured with the pinned babel==2.17.0 on a copy of the committed locale/de/LC_MESSAGES/webui.po (5383 lines):

invocation changed lines (diff) changed non-#: lines
plain pybabel update 4715 3294
--no-wrap 3217 1796
--width=76 (Babel's default) 4715 3294
--width=100 3467 2353
--width=120 1677 675
--width=140 2892 1855
--width=200 2920 1822

No --width=N reproduces the file byte-for-byte (the smallest change, at --width=120, is still 675 non-#: lines) and --no-wrap reflows it too. So step 2 above is a hand insert, not an update: it is the only way to keep the diff a pure addition. The --no-wrap in step 1 styles the throw-away /tmp/webui.pot only and never reaches the catalogs.

Never ship a #, fuzzy entry. pybabel update marks a msgid #, fuzzy when it recognises a previous string as a near-match, and gettext drops fuzzy entries at compile time — so the page silently renders the ENGLISH msgid while the .po looks translated. That class of defect reached review twice (most recently the Settings restart banner in all four non-English catalogs). When an entry is marked fuzzy, either retranslate it or clear its msgstr (an empty msgstr is an honest "not translated yet" — it falls back to the msgid), then remove the flag and recompile. tests/test_webui_i18n.py::test_no_shipped_catalog_carries_a_fuzzy_entry fails on any #, fuzzy entry in any catalog.

Adding a language

  1. pybabel init -i /tmp/webui.pot -d locale -D webui -l <lang> (creates locale/<lang>/LC_MESSAGES/webui.po).
  2. Translate the msgstr lines.
  3. pybabel compile -d locale -D webui.
  4. Add the language's own name to LANGUAGE_NAMES in i18n.py ({"de": "Deutsch"}) — without an entry it appears in the control labelled by its code — and, optionally, its flag to LANGUAGE_FLAGS ({"de": "de.svg"}), dropping the SVG into services/webservice/static/flags/ (public-domain / MIT artwork only; see SOURCE.txt beside the assets). A language with no flag falls back to the neutral globe.

A language appears in the console's language control as soon as its webui.mo exists — the control offers exactly the languages that can render, never an empty one. (The bot's own catalog under locale/de is a different domain and does not make the frontend switch to that language; the bot's catalogs sit beside the console's own webui catalog in the same tree, and it is the webui one the frontend reads.) The list of catalogs is cached (keyed by locale/'s own mtime), so compiling a NEW language is picked up without a restart.

The language control shows flags

With more languages coming, a row of names is too long, so each option is a small SVG flag with the language's own endonym kept as its title (tooltip) and aria-label (accessible name) — the name is not drawn. English is the source language and gets a neutral globe rather than a national flag. Flag EMOJI are deliberately not used: Windows renders them as the two regional-indicator letters, so the control would look broken. The control stays plain links, so it works with JavaScript off.

The language of a request is a code — validated and normalised by normalise_language, so an uppercase DE, a de-DE or a de_DE all read as de.

What a translator touches

Only the .po files. Never the templates, never the Python: those are the source of the msgids and are regenerated by extraction. English is the source language and every English string is its own msgid, so there is no English catalog to copy: a new language starts from the extracted webui.pot.

German is informal (Du). This project's German catalog addresses the reader as Du — "Starte den Server", "Deine Mission" — never the formal "Sie". It is not a pronoun substitution: a sentence that only reads naturally in the formal register is rewritten into an informal one. A writer adding a German string must match that register, and the same convention is noted in the webui.po header so it survives the next extraction.

Spanish is informal (tú). This project's Spanish catalog addresses the reader as tú — "Arranca el servidor", "Tu misión" — never the formal "usted". It is not a pronoun substitution: a sentence that only reads naturally in the formal register is rewritten into an informal one. A writer adding a Spanish string must match that register, and the same convention is noted in the webui.po header so it survives the next extraction.

Russian is informal (ты). This project's Russian catalog addresses the reader as ты — «Запусти сервер», «Твоя миссия» — never the formal «вы». It is not a pronoun substitution: a sentence that only reads naturally in the formal register is rewritten into an informal one. A writer adding a Russian string must match that register, and the same convention is noted in the webui.po header so it survives the next extraction.

Chinese is informal (你). This project's Chinese catalog addresses the reader as 你 — 「启动 服务器」「你的任务」— never the formal 「您」. It matches the bot's own language code: the bot (its catalogs and main.yaml) calls Chinese cn, not zh, so the console's catalog is locale/cn/LC_MESSAGES/webui.po and the console and the bot agree. A writer adding a Chinese string must use 你 and keep that code, and the same convention is noted in the webui.po header so it survives the next extraction.

The language of a request

Highest precedence first:

  1. the visitor's stored choice — the dcssb_lang cookie, set by /language;
  2. the browser's Accept-Language header;
  3. the language: key in main.yaml (the install-wide setting, and the default).

Every value is validated against the languages that have a webui catalog, so an unknown or malformed value is skipped rather than trusted. The choice is stored in its own cookie (not the session) so it survives sign-in — the login and logout flows clear the session for session-fixation defence, and a preference must not be lost to that.

The language is resolved per request and applied through a Jinja environment per language, built lazily and cached — never a global set_language, which would leak the console's language into the bot's Discord strings (the console runs inside the bot's own process).