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
pybabel init -i /tmp/webui.pot -d locale -D webui -l <lang>(createslocale/<lang>/LC_MESSAGES/webui.po).- Translate the
msgstrlines. pybabel compile -d locale -D webui.- Add the language's own name to
LANGUAGE_NAMESini18n.py({"de": "Deutsch"}) — without an entry it appears in the control labelled by its code — and, optionally, its flag toLANGUAGE_FLAGS({"de": "de.svg"}), dropping the SVG intoservices/webservice/static/flags/(public-domain / MIT artwork only; seeSOURCE.txtbeside 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:
- the visitor's stored choice — the
dcssb_langcookie, set by/language; - the browser's
Accept-Languageheader; - the
language:key inmain.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).