Files
dawnline/rules/i18n.md
T
Aemeath dc0f159447
Build packages / CI (push) Blocked by required conditions
Build packages / Version (push) Waiting to run
CI / Web (format, types, tests, bundles) (push) Blocked by required conditions
CI / ShellCheck (push) Blocked by required conditions
CI / ucode static checks (push) Blocked by required conditions
CI / ucode compiles and tests pass (OpenWrt 24.10) (push) Blocked by required conditions
CI / ucode compiles and tests pass (OpenWrt 25.12) (push) Blocked by required conditions
Dawnline 0.14.0
- A device is renamed where its name stands on its card: a click on the
  name, Return or Space on it, or Rename in the ⋯ menu turns it into a
  field with the name selected. Return saves, and the words shimmer until
  the router answers. Esc or a click elsewhere puts the old name back. The
  rename window is gone, and the page no longer redraws under a name being
  edited
- Device names take up to 20 characters: letters of any language, digits,
  spaces and - _ . The router refuses anything else when a device is added
  or renamed, so a name can't carry symbols into configurations, file
  names or the AmneziaVPN key. The portal and the admin turn a character
  like that away as it is typed: the field shakes, its outline goes red
  and a short line says why. Suggested names (a phone's model, "Phone 2")
  are stripped of such characters and cut to fit. Names set before this
  stay as they are
- LAN Bypass: Add a device, in the portal and in the admin, has a switch
  that keeps the device's own local network (printer, TV, NAS) reachable
  while it is connected. It is off by default and stays as chosen; the
  admin's device drawer shows it. With home and internet access the switch
  says which addresses still lead to the home network
- Health warns when a server's home network is on one of the subnets home
  routers come with (192.168.0.x, 192.168.1.x and others). People with
  home access who connect from a network on the same addresses reach your
  home instead of their own, LAN Bypass or not
- The router tells when a device can't connect properly. After the problem
  lasts three minutes, the portal card and the admin drawer name it:
  can't finish connecting (the network may block it), connected but no
  data (an outdated configuration, and the card offers Reconnect), on two
  devices at once, or a connection that keeps dropping. Activity lists
  these under Problems, one line per device per hour, and says when the
  device connects normally again
- The set-up sheet's connection line follows what the device does:
  waiting, can't finish, connected, or connected but no data. The sheet
  closes by itself only once data comes through. On the device itself and
  for a router, the steps regroup to what fixes the problem: "Set it up
  again" when the handshake never finishes, "Add the connection again"
  ("Import the configuration again" for a router) when no data comes
- Set-up in the portal: a QR code too long for a camera to read gives its
  place to a code that opens the set-up link (a LAN Bypass configuration
  or a long AmneziaVPN key can be that long). A TV, box or NAS added from
  a phone gets the steps for setting up from another device. Back from
  "Open on the device" keeps the kind, LAN Bypass and the name typed. The
  packet-size note under the kinds is gone
- The portal on phones keeps its place: nothing jumps when an access row
  opens or folds, a notice comes or goes, or Safari redraws the cards. A
  reload, or coming back from the VPN app, opens where the page was. Cards
  glide to their new height, and an animation interrupted half-way goes on
  from where it is instead of snapping. A double click no longer closes
  the sheet it just opened
- In the admin, a device's drawer has its own MTU and keep-alive (empty
  means the server's), each with a Change dialog. A change touches only
  that device's configuration and restarts nothing on the router. Opening
  the drawer no longer counts as handing out the configuration: "Update
  config" stays until the new configuration is shown as a QR code,
  downloaded or copied ("Show the new configuration"). New keys set the
  device up again, as the portal's Reconnect does
- "Speed now" on a server's Overview is live: one point a second over the
  last two minutes, all there as soon as the Overview opens. The agent
  keeps those two minutes in memory and writes them out only while someone
  is looking
- Disguise values that AmneziaWG refuses or crashes on are stopped before
  they reach the kernel. That covers overlapping H1-H4, Jmin above Jmax,
  broken I1-I5 tags, padding under 12 with header protection, and more.
  Import and restore refuse them. After a hand edit in uci, the server's
  tunnel stays down and Health and the service log say why and what to do.
  Errors are full sentences in the reader's language
- The header protection key no longer shows in the status that read-only
  users can see: the Server page says only that the key is set, and each
  device's configuration still has it. The server no longer turns off
  WireGuard's protection against handshake floods (devices keep
  DisableCookies). A device can't be added with a server's own key
- An AmneziaWG update whose kernel module can't be swapped (another
  AmneziaWG interface holds the old one) no longer fails. It is installed,
  the tunnels come back on the old module, and Health and Components say
  the update starts after a reboot. On apk firmware, an install that apk
  left at the old version counts as failed. A module installed by hand is
  recorded, so after a firmware upgrade Health can tell that it is gone
- Dawnline reads only its own tunnels, each one separately. Another
  AmneziaWG interface on the router no longer slows the agent's
  once-a-second check, has its keys read or breaks Dawnline's reads. A
  portal request reads only that person's server: one process however many
  servers there are
- Fewer false disconnects: a tunnel that netifd sets up again no longer
  logs everyone as leaving and coming back, and a device with a long
  keep-alive stays online between handshakes. One configuration on two
  devices isn't logged as roaming every few seconds, and new keys end the
  old session at once. A tunnel that is missing devices is synced within a
  minute, and traffic across a tunnel restart is no longer undercounted
- Renaming a server no longer restarts its tunnel. If a tunnel's interface
  is edited outside Dawnline (LuCI, uci), the watchdog sets it up again
  with Dawnline's settings and names only the changed options. The routing
  rules for "Internet like a home device" change one at a time, new ones
  first, so traffic never falls between them. Health and the Server page
  warn when the address's AAAA record isn't this router's, or the router
  has no public IPv6: devices that prefer IPv6 fail to connect
- The README screenshots come in English and Russian; the portal's are
  taken from its demo. The demo has a switch beside × in the set-up sheet
  to show each state of the connection line. In Russian, long labels in
  the admin's wide option buttons wrap under their icon. DESIGN.md
  describes the switch, renaming on the card, the shimmer, the shake and
  how the portal scrolls. New tests cover link states, the meter, access,
  Health, firewall rules, network settings and packages
2026-10-22 00:11:50 +03:00

99 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.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** (ucode: `die()` texts, health checks, endpoint verdicts, the updater's phases) go through `_()` / `N_()` from `dawnline.i18n` and are in the `dawnline` catalog too. The admin page sends its language with every RPC call (`lang`, added by `web/src/admin/api.ts` and stripped by `rpcd/ucode/luci.dawnline`), the updater gets it from the job's start (`DAWNLINE_LANG`), the portal's CGI from `Accept-Language` (the portal's fetch sends the visitor's choice). `dawnline.i18n` reads LuCI's catalog through `luci.core`, so the backend speaks Russian where `luci-i18n-dawnline-ru` is installed; the portal page translates what reaches it in English from `portal.uc`, `devices.uc`, `core.uc` and `awg.uc` with its own catalog. The agent's and the CLI's terminal output stay English. Text the backend stores and shows later is stored as a code (or, for service log lines, as `L_()` templates) and put into words when it is read.
- **Delivery.** The release has `luci-i18n-dawnline-ru-<version>.{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 `<b>`): `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 дня |
| allowed hours; outside allowed hours | часы доступа; вне часов доступа |
| 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 | Отменить |