Dashboards internationalization

Locales, typed catalogs, the dashboard locale prop, and the fixed product date format. For the steps to translate a dashboard, see Localize a dashboard.

Supported locales

AppLocale in @overvis/hmi-shared:

Code	Language
en	English (base)
pl	Polish
de	German, native label Deutsch, short label DE
uk	Ukrainian (UI short label UA, not UK)
ru	Russian

export const appLocales = ["en", "pl", "de", "uk", "ru"] as const;
export type AppLocale = (typeof appLocales)[number];
export const baseLocale: AppLocale = "en";

Unknown locale strings coerce to en via coerceAppLocale.

Typed catalogs (host and Setup)

The host application and workspace-ui use typed TypeScript catalogs for all product chrome and Setup strings:

• Sidebar, setup labels, validation, dashboard load failures
• Parameter runtime error labels and write-reason details
• Form banners and field errors via mapped tRPC codes

The host picks the language saved in this browser (local storage, then a cookie), then the browser’s preferred languages, and finally English.

LanguageSwitcher and setLocale load the requested catalogs and update the host locale without reloading the page. Unsaved form values and open dialogs are preserved. If loading fails, the current language stays active and the operator can retry. Dashboard mounts negotiate the locale prop against the languages declared by the dashboard module.

The API sends no UI text (except emails and notifications): error responses carry codes, and their English message is for logs.

useTranslation() from @overvis/hmi-workspace-ui/i18n reads the shared UI messages of the host catalogs, in the host’s active locale. Shared UI components also use the host’s active locale. A dashboard module’s own copy is not in the host catalogs, and the host does not translate strings inside the module.

Dashboard locale prop

DashboardRootProps.locale is an AppLocale. The entry module exports a literal supportedLocales array listing the languages its copy implements. When it is declared in manifest.ts and re-exported from the entry (export { supportedLocales } from "./manifest.ts";), the build also records it in hmi-dashboard.json. The host passes the active UI language when that list contains it and English otherwise. English must be included; duplicates, unknown locale codes, empty arrays, and non-array declarations fail module validation.

export const supportedLocales = ["en", "pl", "de", "uk", "ru"] as const;

A module without the export is treated as supporting en, pl, uk, and ru, and gets English under a German UI. This changes neither stored dashboard content nor the surrounding UI language. The host’s live appLocales may gain languages after a bundle is built, so a bundle that re-exports it can declare languages its copy does not implement.

The host language switcher displays English, Polski, Deutsch, Українська, and Русский, in that order. Switching updates the active language for Setup strings and negotiates the dashboard locale again; the new locale reaches the mounted module as a prop. props.theme ("light" or "dark") changes independently of the locale.

appLocaleUiCode gives the short code of each locale:

Locale	Short UI code
en	EN
pl	PL
de	DE
uk	UA
ru	RU

Date and time format

Dates and times in dashboard-owned UI, Setup, and cloud chrome use one format:

YYYY-MM-DD HH:mm:ss

• The format is fixed and independent of the locale.
• Times are in the viewer’s browser time zone.
• formatAppDateTime(input) from @overvis/hmi-shared formats a Date, an ISO string, or epoch milliseconds this way.

toLocaleString() can change month names or their order with the locale, so its output does not match the product format.

Embedded report widgets follow the report page time zone instead. The preset’s browser setting resolves to the viewer’s time zone; an explicit time zone applies to report timestamps and aggregation boundaries. formatReportDateTime formats report data in the report’s resolved time zone, and parseReportDateTime parses report wall times. The built-in report widgets handle this themselves.

Parameter date-time values

A parameter whose valueType.name is "datetime" uses ISO-8601 as its canonical stored and string value for reads and writes. That is separate from UI formatting:

• The read value is an ISO string, and an ISO string is what a write sends back.
• Setup’s live value cell shows it with formatAppDateTime(...) (YYYY-MM-DD HH:mm:ss in the browser time zone).
• In Setup, editors type the same UI form; the cell parses it with parseAppDateTime and writes ISO back.

Setup’s date-time displayFormat default often mirrors YYYY-MM-DD HH:mm:ss; the canonical value remains ISO.

Numbers and units

Canonical parameter num strings use . as the decimal separator in the product interchange format, whatever the locale; the value type expects its canonical form in writes. Engineering units come from the parameter’s units or from the dashboard’s own labels. The locale adds no unit.

Error and validation copy

Surface	Source of the text
Setup forms	Typed catalogs with mapTrpcToFormErrors and apiErrorMessage
Setup live parameter widget	Translated runtime error helpers
Dashboard parameter I/O	The dashboard’s own map keyed by error.code and reason
Dashboard load failure	Translated host notice, outside the dashboard component

The runtime codes are listed in Live value procedures.

Assistant replies

The assistant answers in the language of the user’s message, independently of the dashboard locale prop. Its replies do not go through the catalogs.

Related packages

Package	i18n role
@overvis/hmi-shared	AppLocale, coerce helpers, formatAppDateTime
@overvis/hmi-workspace-ui	Setup and shell catalogs; ./i18n hooks
Dashboard ESM	Author-owned message tables

Related

• Localize a dashboard
• Develop a dashboard locally
• Dashboard UI and forms
• Live data in dashboards
• @overvis/hmi-shared: locale helpers and formatAppDateTime / parseAppDateTime