tajniak81andClaude Opus 5
dc6febf815
Three loose ends from the last two commits, each of which was named as deliberately-not-done and none of which is worth carrying further. The phone's create-user sheet had no organization picker. The endpoint has taken an `organization` since orgs existed and the Web App has offered the choice all along, so a superadmin on the phone could only ever create accounts in their own org - a silent restriction rather than a stated one. The sheet now loads the orgs and offers them to a superadmin, with the same blank "no organization" option and the same hint as the web. An admin still gets no picker, because the server forces its own org on their members and a picker that cannot change the outcome is a lie. The listing is manager-only and can fail, in which case the picker offers only "no organization" rather than blocking the form. A locked role picker or delete action was greyed out with no reason given. The web has explained itself in a title attribute since those guards existed, and the sentences - admin.cantChangeOwnRole and the rest - have been sitting translated in the phone's own language files since the screen was translated. Hover has no touch equivalent, so the two controls take different routes: a long-press on the role picker shows the reason as a tooltip, and the overflow menu carries it under the action, because a disabled menu item cannot be long-pressed and silently greying it out is the thing being fixed. settings.integrations.* and charging.control.* were English-only in *both* apps - 70 keys, identical text, identical key sets - so they are translated once and land in all four language files. OCPP and CSMS are protocol names and stay; product names (Toyota Connected, MyToyota, Anker Solix, Lexus) stay; everything else follows the wording already in each language's file. The Web App's files are edited as text rather than round-tripped through a JSON dump, because they keep a blank line before every nested block and a dump flattens it - a 900-line translation file is hard enough to read without losing its paragraphs. Both diffs are purely additive as a result. Both apps now have every key in all three languages: 738 in the web, and the phone reports zero fallbacks. A new test locks that in - every key en.json carries must exist in pl.json and da.json - and it was checked by deleting a key and watching it fail, because a guard that cannot fire is not a guard. Verified by flutter analyze (clean), flutter test - 21 pass, 1 of them new - flutter build apk --debug, and npm run build for the Web App. The key checker reports 575 static t() keys in the phone and 738 in the web resolving with no fallbacks in either language. Not verified: still nothing run against a live API Server or on a device. In particular the organization picker's happy path - a superadmin creating an account into a chosen org - has not been exercised end to end; it is the one piece here that touches the API rather than only the language files. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
116 lines
6.0 KiB
Markdown
116 lines
6.0 KiB
Markdown
# Translations (i18n)
|
|
|
|
DriverVault's user interface is translatable. Each surface reads its text from
|
|
**per-language files** — nothing hardcodes English in the parts that have been
|
|
converted — so adding a language is a matter of dropping in a new file, not
|
|
editing screens.
|
|
|
|
Three languages ship today: **English (`en`)**, **Polish (`pl`)** and
|
|
**Danish (`da`)**. English is the base and the fallback: any key missing from
|
|
another language renders the English string, so a partial translation is always
|
|
safe to ship.
|
|
|
|
The language is the **language half of the user's BCP-47 locale**
|
|
(`locale` = `language-REGION`, e.g. `pl-PL`). The Settings **Language** picker
|
|
sets it; the **Region** half keeps steering date, number and currency formatting
|
|
independently, so the two can be mixed freely (English text with Polish number
|
|
formatting, say). The picker offers every European language because the choice
|
|
also drives date/number formatting — the ones without a translation file fall
|
|
back to English UI text and say so beneath the picker.
|
|
|
|
## Where the files live
|
|
|
|
| Surface | Language files | Loader | Language source |
|
|
|---|---|---|---|
|
|
| **Web App** (Vue) | `Web App/web/src/i18n/{en,pl,da}.json` | `Web App/web/src/i18n/index.js` | signed-in profile `locale` (reactive `prefs`) |
|
|
| **API Server panel** (Vue) | `API Server/panel/src/i18n/{en,pl,da}.json` | `API Server/panel/src/i18n/index.js` | `localStorage` (`dh-panel-lang`) — the panel has no user profile |
|
|
| **Phone App** (Flutter) | `Phone App/assets/i18n/{en,pl,da}.json` | `Phone App/lib/i18n.dart` | signed-in profile `locale` (via `AppSettings`) |
|
|
|
|
All three use the same JSON shape and the same `t()` contract, so a translator
|
|
learns one format.
|
|
|
|
## The `t()` contract
|
|
|
|
```js
|
|
t("settings.appearance.title") // simple lookup (dot path = JSON nesting)
|
|
t("forms.share.title", { name: car.name }) // {name} placeholder interpolation
|
|
t("dashboard.serviceRecords", { n: count }) // plural — see below
|
|
```
|
|
|
|
- **Keys** are dot paths matching the nesting in the JSON.
|
|
- **Placeholders** are named (`{name}`), never positional, so a translator can
|
|
reorder them to suit the target grammar.
|
|
- **Plurals** are an object keyed by CLDR category, selected for the active
|
|
language by `Intl.PluralRules` (web/panel) or `Intl.plural` (Flutter):
|
|
|
|
```json
|
|
"serviceRecords": {
|
|
"one": "{n} service record",
|
|
"other": "{n} service records"
|
|
}
|
|
```
|
|
|
|
This is why Polish works: it needs `one` / `few` / `many` where English has
|
|
only `one` / `other`, and a naive `n === 1` check would get "5 samochodów"
|
|
wrong. Polish files therefore carry all four forms.
|
|
|
|
- The web/panel loaders also expose `tSplit(key, name)` for the few strings that
|
|
wrap one value in its own markup (a monospace URL, a bolded car name). It
|
|
returns `{ before, after }` around the placeholder so the value keeps its
|
|
styling without splitting the sentence into word-order-assuming fragments or
|
|
putting a translated string on a `v-html` path.
|
|
|
|
## Adding a language
|
|
|
|
1. **Copy `en.json` to `<code>.json`** in each surface you want to cover
|
|
(`fr.json`, say) and translate the string values. Keep the keys and the
|
|
`{placeholders}` unchanged. For a language with more plural categories than
|
|
English, expand the plural objects (`one`/`few`/`many`/`other` as CLDR
|
|
requires for that language).
|
|
2. **Register it** in the loader's `MESSAGES` map / `translatedLanguages` list:
|
|
- Web: `Web App/web/src/i18n/index.js` — add to the `import`s and `MESSAGES`.
|
|
- Panel: `API Server/panel/src/i18n/index.js` — same.
|
|
- Phone: `Phone App/lib/i18n.dart` — add the code to `translatedLanguages`
|
|
(the file is loaded from `assets/i18n/` automatically; it's covered by the
|
|
`assets/i18n/` directory entry in `pubspec.yaml`).
|
|
3. The Settings picker already lists every European language, so the new one
|
|
becomes selectable immediately and the "not translated yet" hint disappears
|
|
for it. Untranslated keys still fall back to English.
|
|
|
|
No screen code changes are needed to add a language.
|
|
|
|
## Coverage
|
|
|
|
- **Web App** — fully translated: every view, component, form, and the status
|
|
labels in `lib/format.js`.
|
|
Both apps are complete in all three languages. The one place the wording is
|
|
deliberately not translated is proper nouns: protocol and product names (OCPP,
|
|
CSMS, Toyota Connected, MyToyota, Anker Solix, Lexus) read the same in every
|
|
file, as do the units.
|
|
|
|
- **API Server panel** — UI chrome, cards, login, status, and the API section
|
|
titles are translated. The individual REST endpoint **descriptions** in the
|
|
API reference table are intentionally left in English as developer reference
|
|
documentation.
|
|
- **Phone App** — navigation, login, lock screen, dashboard, the full Settings
|
|
panel (including the language picker), the status/badge wording in
|
|
`lib/format.dart`, the admin users screen, and the whole car screen: its tabs,
|
|
every record tile, the share and delete-car dialogs, and all of the form sheets
|
|
(`car_form_sheet`, `record_form_sheets`, `attachment_field`).
|
|
|
|
The strings the two apps share are **copied out of `Web App/web/src/i18n/`**
|
|
rather than retyped, so a phrase has one translation across both and cannot
|
|
drift. Only what the phone alone needs is written here: tooltips (the web
|
|
labels its buttons), the record tiles' running prose (the web lays the same
|
|
data out as table columns), client-side validation (the web leans on the
|
|
browser's `required`), and the snackbars.
|
|
|
|
`test/models_format_test.dart` guards two things the analyzer cannot see. The
|
|
lookups built from a key at render time (`car.tabs.$key`, `enums.fuelType.$v`,
|
|
`admin.roles.$r`, the delete dialog's plural counts, the connected service's
|
|
readings) must resolve to a real label in every language — a catalogue entry
|
|
with no translation fails the test rather than reaching a screen as a raw key
|
|
path. And every key `en.json` carries must exist in `pl.json` and `da.json`,
|
|
so a phrase added in English alone is caught at the point it is added rather
|
|
than by whoever next reads a half-translated screen.
|