Localize a dashboard

This guide translates a dashboard you develop locally. The locale prop, date format, and catalogs are described in Dashboards internationalization.

A shared dashboard should cover all five product languages: en, pl, de, uk, and ru. A smaller set must include English, which operators of the other languages get.

Declare the supported languages

In manifest.ts, export a literal supportedLocales array with English and each language your copy implements:
```
export const supportedLocales = ["en", "pl", "de", "uk", "ru"] as const;
```
Re-export it from the entry: export { supportedLocales } from "./manifest.ts";.
Do not re-export the host’s appLocales. It may gain languages after your bundle is built.

Translate the dashboard’s own copy

Keep the dashboard’s strings, such as machine names and button labels, in a message map in the dashboard folder, so the module stays self-contained:

const messages = {
  en: { title: "Status" },
  pl: { title: "Status" },
  de: { title: "Status" },
  uk: { title: "Статус" },
  ru: { title: "Статус" },
} as const;

function t(locale: AppLocale) {
  return messages[locale] ?? messages.en;
}

Pick the copy from props.locale on every render, and fall back to en when a key is missing. Do not keep the locale in module-level state or in a value captured at first mount: a language switch then leaves the old copy on screen.
For the shared UI messages of the host, use useTranslation() from @overvis/hmi-workspace-ui/i18n.
For a language indicator of your own, use the short codes of appLocaleUiCode.
When operators edit titles through the configuration JSON, document for each language which configuration labels they edit.

Format dates and numbers

Format product timestamps, including datetime parameter values, with formatAppDateTime from @overvis/hmi-shared. It gives YYYY-MM-DD HH:mm:ss in the browser time zone. Do not use toLocaleString().
For report data, use formatReportDateTime with the report’s resolved time zone.
When you write a number back, send the canonical form the value type expects, typically with . as the decimal separator, even if you display it differently.
Show units from the parameter or from your own labels. Do not expect the locale to add °C.

Translate runtime errors

Map runtime errors to text by error.code and reason. Never show the English message.

Keep a small error table in the dashboard, unless an import-map entry such as @overvis/hmi-workspace-ui/i18n already provides the text:

const runtimeErrors = {
  en: { timeout: "Timeout", endpoint_disconnected: "Endpoint disconnected" },
  pl: { timeout: "Limit czasu", endpoint_disconnected: "Endpoint rozłączony" },
  de: { timeout: "Zeitüberschreitung", endpoint_disconnected: "Verbindung getrennt" },
  uk: { timeout: "Тайм-аут", endpoint_disconnected: "Endpoint відключено" },
  ru: { timeout: "Тайм-аут", endpoint_disconnected: "Endpoint отключён" },
} as const;

Extend it with the full code list from runtime error codes for production dashboards.

ParameterDiagnostics and the device dashboard components translate their built-in copy through the host catalogs, in the host’s locale. Texts you pass to them are yours to translate.

Check the result

Switch the host language through all five locales and confirm that the dashboard’s strings change.
Toggle the theme and confirm the contrast.
Render formatAppDateTime(new Date()) and confirm the YYYY-MM-DD HH:mm:ss format.
Force a timeout or param_disabled error and confirm that the dashboard shows translated text, not the English message.