This page was generated from the source of RoboHub. Edit the source, not this page.
Internationalisation
The module keeps a Rho page in the language the request asked for. Catalogs are
flat JSON files embedded by the host at build time; this module never parses a
file and never calls a network service.
How an application uses it
Add i18n to deps and include it. It needs no host hooks; it registers
POST /i18n/locale on the application's router. Every shared module whose pages
are translated (appshell, inventory, scheduler, rules, widgets,
journal) depends on it.
Catalogs
A catalog is a flat JSON file per language. A module ships its own in its
module.yml:
locales:
- locale: en
file: locales/en.json
- locale: ro
file: locales/ro.json
and the application lists its own in its target in project.yml, with the
language a request gets when it names none:
targets:
- id: go-server
default_locale: en
locales:
- locale: en
file: locales/en.json
- locale: ro
file: locales/ro.json
The build embeds every catalog: the included modules' first, the application's
last. A later catalog overrides an earlier one, so an application can say a module's
word its own way. A file is a flat object of string values:
{
"dashboard.title": "System Status",
"dashboard.temp": "Temperature: {{val}}°C"
}
Templates
<h1>{{t "dashboard.title"}}</h1>
<p>{{t "dashboard.temp" val=current_temp}}</p>
{{val}} in the catalog is replaced with the current template value and
escaped. A missing key falls back to the default language, then prints the key.
The active language is the reserved __locale value. i18n_vars(req) adds it,
and the switcher, to a page fill:
let body: string = template_fill(template_get("page"), vars("body", body) + i18n_vars(req))
Choosing a language
- the
localecookie, if it names a supported catalog; - the first supported
Accept-Languagetag; en.
The supported languages are en and ro; a regional tag falls back to its
primary language (ro-RO is ro). i18n_switcher(req) draws the language
buttons (the locale_switch value i18n_vars adds), and the person's menu in
the top bar offers the same choice (see ui/index). Either posts to
/i18n/locale, which sets the locale cookie for a year and redirects to the
next path — only a path on this origin (i18n_safe_next). It also sends HX-Redirect, so an HTMX form works without a special client
path.
Outside a template
i18n_t(req, key) translates a key for a notice or an error, and
i18n_locale(req) is the language a request is answered in.
An application that writes its labels in English can carry a catalog of whole
labels instead: phrases.<locale>.txt in a folder of its own, English and the
translation separated by a tab, one per line. i18n_phrases(req, html, folder)
turns a page into the request's language, replacing a label only where it is a
whole text between tags, a placeholder or a title; a whole page also carries the
catalog, so what arrives later (htmx, a live stream) is translated in the
browser.
Coverage
The build compares each non-default catalog with the default one and prints
the number of missing keys, with the first key, plus any key the locale has that
the default does not. Missing keys fall back to the default language; the
warning is a prompt to finish the translation, not a build failure.
Live fragments carry the language in their event name, for example
widget-1-en and widget-1-ro, because one SSE connection serves clients that
may have chosen different languages.
Reference
Generated from the module's manifest and sources when this site was built.
Exports — what an application may call (provides.exports, imported as robohub.i18n):
i18n_ti18n_varsi18n_localei18n_switcheri18n_phrasesi18n_safe_next
Routes — registered on the host application's router:
| Method | Path | Handler |
|---|---|---|
| POST | /i18n/locale | i18n_switch |
Release history
[0.1.0] - 2026-11-08
First release. Adds locale negotiation from a cookie or Accept-Language, the language switcher, and i18n_vars for Rho page helpers. Ships English and Romanian shared catalogs.
[0.2.0] - 2026-11-12
The module publishes its interface: it is imported as robohub.i18n, and exports i18n_t, i18n_vars, i18n_locale, i18n_switcher. Everything else in it is its own, so an application that imports it cannot reach its helpers, and they never collide with the application's own names. Including it by name still works and is reported with the import to use instead.
[0.3.0] - 2026-11-12
The language switcher reads its form through the form engine, which i18n now declares as a dependency, instead of a form_value the including application happened to define. The module builds on its own.
[0.4.0] - 2026-11-13
Whole labels. An application that writes its labels in English carries a catalog per language (phrases.<locale>.txt, English and the translation separated by a tab), and i18n_phrases(req, html, folder) turns a page into the request's language: a label is replaced only where it is a whole text between tags, a placeholder or a title, a translation is never translated again, and what a page receives later is translated in the browser from the same catalog. It was Mesh's; every application has it now.
[0.4.1] - 2026-11-13
The language switch returns only to a path on the same origin: a backslash (/\\evil.example, another host to a browser), a quote, an angle bracket, a space or a line break (another response header) sends it to / instead.
[0.4.2] - 2026-11-14
Trimming comes from the toolchain (str_trim, rho 0.7.0) rather than this module's own copy.
[0.4.3] - 2026-11-14
Copies of helpers the toolchain now provides (i64_to_str, str_lower, str_field, json_str_field, escape_html) are gone. Needs rho 0.8.0.
[0.4.4] - 2026-11-14
i18n_safe_next is exported: an application that redirects back after a language switch uses it, and a build said it was not promised. The copy of a replace-all helper is gone for the toolchain's str_replace (rho 0.8.3), which this module needs.