# Translations (admin UI, portal, backend messages) Dawnline is written in English and translated through gettext catalogs. Russian is the first translation. Read with `frontend.md` (and `backend-go.md` for messages the router sends). ## The rule - **What is added is localized in the same change.** A new page, section, control, toast, error, check or log line in the admin UI, the portal or the backend comes with its strings wrapped (`_()`, `N_()`, `plural()`, `L_()`) and translated in every `ru.po`. Not "later": CI refuses a catalog with an untranslated string. - **What is removed leaves nothing behind.** Deleting or rewording text deletes its old entries: `npm run i18n` drops every entry no code uses any more, and `npm run i18n:check` (CI) fails while a catalog still holds one. No dead entries, no hand-kept leftovers, no commented-out translations: the catalogs follow the code, as the code follows `code-standards.md` ("Delete, don't deprecate"). - **Every change to visible text is checked in Russian too**: the wording against the glossary below, the layout at narrow widths (Russian runs longer). ## How it fits together - **Admin UI (LuCI).** Every visible string goes through LuCI's globals `_()` and `N_()`. The catalog is `package/luci-app-dawnline/po/ru/dawnline.po`; luci.mk compiles it with po2lmo into the separate package `luci-i18n-dawnline-ru` (`/usr/lib/lua/luci/i18n/dawnline.ru.lmo`, plus the uci-defaults that adds Russian to LuCI's languages). LuCI loads it when the page language is Russian (`luci.main.lang`, or `auto` with a Russian browser). Without the package everything stays English. The LuCI menu titles (`menu.d`) are in the same catalog. - **Portal.** Not LuCI: it carries its own catalog (`web/src/portal/i18n/ru.po`, made into a lookup table at build time and bundled into `portal.js`), so it speaks Russian on every router, with or without the admin's package. `portal/i18n.ts` installs `_()`/`N_()` with LuCI's meaning, opens in the visitor's kept choice or the browser's language, and the language menu in the breadcrumb switches it in place. The demo's own strings are in `web/src/portal/demo/i18n/`. - **Shared code** (`web/src/shared`) runs in both and is in both catalogs. - **Backend messages** (refusals, health checks, endpoint verdicts, the updater's phases, the portal's answers) are English sentences in the Go code, put into the reader's language by the catalog (`i18n.Catalog.T`, `N`) and listed in `backend/i18n/messages.js` (and `portal-messages.js` for what reaches the portal's visitors): the extractor reads those two files, not Go. **A sentence the backend says that is not listed there has no translation**: add or change it there in the same change, then `npm run i18n` and translate. `L_()` there marks a line of the service log (written in English, translated where it is shown). The admin page sends its language with every call (`lang`, added by `web/src/admin/api.ts`), the updater gets it from the job's start (`DAWNLINE_LANG`), the portal from `Accept-Language`. - **Delivery.** The release has `luci-i18n-dawnline-ru-.{ipk,apk}` next to the app. `install.sh` adds it when LuCI is in Russian (its setting, or `luci-i18n-base-ru` installed) or with `--lang ru`; the updater installs it with every Dawnline update when it is installed; Components → Dawnline → Translation adds or removes it. LuCI reads a language's catalogs once per web server process, so each of these restarts uhttpd afterwards. - **Collecting.** `npm run i18n` (in `web/`) reads the code and rewrites the `.pot` templates and the `.po` files: new strings are added untranslated, gone ones removed, translations kept (and reused across catalogs). `npm run i18n:check` (CI) fails when a catalog is out of date, a string is untranslated, or a translation lost a placeholder. After changing visible text: run `npm run i18n`, translate the new entries in each `ru.po`, commit the catalogs with the code. ## Writing strings - **Every visible string is wrapped**: text, buttons, headings, toasts, errors, tooltips (`title`), `aria-label`, `placeholder`, `alt`, the page title, confirm dialogs, CSV headers. Not wrapped: product and protocol names standing alone (Dawnline, AmneziaWG, WireGuard, OpenWrt, LuCI), ids, keys, paths, commands, package names, CSS classes, URLs, values sent to the router, log/event ids, `console` output. - **Literals only.** `_('Save')`, never `_(label)` or `` _(`Hello ${name}`) ``: the extractor cannot collect them and fails. Placeholders `%s` (or `%d`) are filled with `fmt()` from `shared/i18n.ts`: `fmt(_('Removed %s'), name)`. - **Whole sentences.** Never glue a sentence from pieces (`'Removed ' + name + ' from ' + circle`, or `_('ends') + ' ' + date`): word order and case endings differ. One msgid per sentence with placeholders. Pieces joined by separators (`PC · 10.0.0.2 · online`) are separate facts and stay separate strings. - **Elements inside a sentence** (a link, a ``): `fill(_('Install it in %s'), link)` returns the children for `E()` / `h()`. The link text is its own `_()`. - **Counts** go through `plural(n, '%s device', '%s devices')` (number formatted, both forms literals) or `N_(n, 'Device', 'Devices')` when the number is not in the text. Never `n === 1 ? … : …` or `` `${n} devices` ``: Russian has three forms (1 устройство, 2 устройства, 5 устройств), and 21 takes the singular. Use them even where English always has the plural. - **Numbers and dates** in the page's language: `num(n)` (2,000 / 2 000), `num(v, 1)` for one decimal, `bytes()`, `fmtDay()`, `toLocaleDateString(locale(), …)`. Never a hard-coded `'en-GB'` or `toFixed()` for shown numbers. - **Text is made when it is drawn**, inside functions, never at module level in the portal and the shared code (the portal changes language in place; the extractor refuses it there). A table of labels becomes a function: `kindLabel(k)` in `shared/format.ts`. - **Context** when one English word means two things: `_('Off', 'state')` vs `_('Off', 'switch')`. Use it only for real clashes. - **Whitespace and line breaks** are not part of a msgid: no leading/trailing spaces, no double spaces, no `\n` (LuCI squeezes whitespace before the lookup; po2lmo cannot carry newlines). Put spacing in the markup or the separator. - **Keep the English as it is** when wrapping, except to turn a glued sentence into one with placeholders. - **Other apps' labels** (the menus of AmneziaVPN, WireGuard and AmneziaWG in set-up steps) are quoted word for word, with a context of their own (`_('Create from QR code', 'WireGuard app')`), and translated with the app's own Russian from its sources (English where the app has no Russian). Where they come from is noted in `portal/setup.ts`. - **Messages from the router** arrive in the page's language already (admin) or are translated with `routerText()` (portal): never glue them into a sentence of the page's own; ask the backend for a whole sentence instead. ## Writing backend messages - `import { _, N_ } from 'dawnline.i18n';` and wrap literals only: `die(_('Backup not found.'))`, `die(sprintf(_('Download failed: %s'), asset))`, `sprintf(N_(n, '%d device', '%d devices'), n)`. Placeholders `%s` and `%d` only, filled after the lookup. - `_()` inside functions only: rpcd keeps the modules loaded and the language changes with each call (the extractor refuses module-level calls). - Wrap what a person reads in LuCI or the portal; leave ids, status values, command lines and sentinels alone. - Messages a portal visitor can get belong in `portal.uc` or `devices.uc` and are best static sentences: the page can translate those without the package. - **Service log lines** (`slog()` and the watchdog's problem/back/what texts) are written once, in English, by processes with no language (the agent), and read later. Mark their words with `L_()` instead of `_()`: `slog('awg', 'up', sprintf(L_('updated · %s → %s'), a, b), null, L_('System packages'))`. `L_` returns the English; the extractor collects it into the catalog and into `web/src/admin/events/log-templates.ts`, and the admin page matches each line against those templates and translates it (`logText()` in `events/model.ts`), values and nested templates included. Keep a template's English when you touch it (lines already in logs match it), and give the Russian the agreement its subject needs; a translation may start with «:» to go on after the subject («Сервер Home: AmneziaWG не работает»). ## Russian Write like a careful Russian product (Telegram, Яндекс), not a word-for-word translation. - **Tone:** polite and short, «вы» in lower case. Buttons and menu items are verbs in the infinitive (perfective where it fits): «Сохранить», «Удалить», «Скопировать», «Добавить устройство», «Изменить»; «Отмена» for Cancel, «Закрыть», «Готово», «Назад», «Далее». - **States** in forms that fit any person: «На паузе» (not «Приостановлен/а»), «Доступ закончился», «В сети» / «Не в сети». Prefer constructions without gender; when unavoidable, masculine as the neutral form. - **Typography:** «ёлочки» for quotes, «ё» where it belongs (ещё, всё, истёк), the ellipsis character «…». No em dashes (—): where a dash is needed, a plain one with spaces ( - ), or a colon or a comma (the catalog check refuses «—»). Ranges keep the en dash (1–32, 07:00–23:00). Numbers with a space before units: «1,5 ГБ», «20 Мбит/с». - **Units:** Б, КБ, МБ, ГБ, ТБ; бит/с, кбит/с, Мбит/с, Гбит/с; «5 мин назад», «3 ч назад», «2 дн. назад»; «2 д 5 ч», «5 ч 12 мин», «12 мин». - **Length:** Russian runs ~20–30% longer. Keep buttons, pills, tabs and segmented controls short (abbreviate or rephrase), and check the layout in the browser at narrow widths. - **Product and technical names stay as they are:** Dawnline, AmneziaWG, AmneziaVPN, WireGuard, OpenWrt, LuCI, GitHub, Cloudflare, Let's Encrypt, DDNS, DNS, MTU, UDP, TCP, IPv4/IPv6, NAT, CGNAT, LAN, WAN, QR-код, opkg/apk. ### Glossary | English | Russian | |---|---| | server | сервер | | person / people (the page) | человек / люди («Люди»); Add person — «Добавить человека» | | device | устройство | | circle | круг | | access | доступ | | home network | домашняя сеть | | internet | интернет | | home network + internet | домашняя сеть и интернет | | LAN Bypass (a device's option) | обход локальной сети («Обход локальной сети») | | portal, personal link, personal page | портал, личная ссылка, личная страница | | invite (card) | приглашение (карточка приглашения) | | disguise; Off / Balanced / Maximum | маскировка; Выкл. / Сбалансированная / Максимальная | | data limit | лимит трафика | | usage, traffic | трафик | | end date; ends in 3 days | дата окончания; закончится через 3 дня | | pause / resume; paused | приостановить / возобновить; на паузе | | online / offline; last seen 12 min ago | в сети / не в сети; «В сети 12 мин назад» (not «Было в сети») | | set up a device; setup | настроить устройство; настройка | | app | приложение | | key, public key, private key | ключ, публичный ключ, приватный ключ | | configuration file (.conf) | файл конфигурации (.conf) | | endpoint, public address | адрес сервера, публичный адрес | | port, port forward | порт, проброс порта | | tunnel | туннель | | handshake | рукопожатие | | router | роутер | | firewall, zone | межсетевой экран, зона | | interface, network | интерфейс, сеть | | certificate | сертификат | | Overview / Servers / People / Activity | Обзор / Серверы / Люди / События | | Diagnostics / Health / Logs | Диагностика / Состояние / Журналы | | Settings / Components / Updates | Настройки / Компоненты / Обновления | | backup, restore | резервная копия, восстановить | | check (health), fix | проверка, исправить | | What's new | Что нового | | Advanced | Дополнительно | | watchdog | автовосстановление | | places (map) | места | | Copied | Скопировано | | Undo | Отменить |