tajniak81andClaude Opus 5
a2d9efec7e
The previous commit left the car screen half translated: its tab labels went
through t(), and everything underneath them did not. A Polish user opening a
car got translated tabs over English tiles, English forms and English
dialogs, which is worse than either extreme because it reads as a bug rather
than as a missing translation.
So the whole screen and everything it opens now reads from the language
files: the record tiles, the share and delete-car dialogs, the service and
part sheets it hosts, record_form_sheets.dart, car_form_sheet.dart, and the
attachment field whose buttons surface inside all of them.
Almost none of these strings are new. The Web App has said all of this in
three languages since b6bb6b1, so forms.*, enums.*, attachment.* and errors.*
are copied out of its language files the same way car.* was, and Polish and
Danish arrive complete. What is written here is only what the phone alone
needs, and the categories are worth naming because they are the reason the
two apps' files are not identical: tooltips, because the web labels its
buttons; the tiles' running prose, because the web lays the same data out as
table columns; client-side validation, because the web leans on the browser's
`required`; and the snackbars.
Three things changed shape rather than just wording.
The per-record delete prompts were one template with a noun slotted in -
"Delete this $what?" - which does not survive translation into a language
that inflects the noun. Each collection now names its own confirmation
string, which is what the web already had.
The delete-car dialog counted with a hand-rolled `"$n $noun${n == 1 ? '' :
's'}"`. Polish has three plural forms, so that could not be translated at
all; it now goes through the CLDR plurals in car.delete.*. It also only ever
named service records and parts, while the cascade takes maintenance, fuel,
charges and documents too - the translated body names all six, so it is now
passed the whole data set rather than two counts.
The enum labels (fuel types, maintenance type/status, document and reminder
types) were four const maps duplicated between the tiles and the pickers.
They are one lookup against enums.* now, with an unknown value falling back
to the raw key rather than a blank - the server owns that enum, and a value
added there should stay legible in an app that has not caught up.
Found and fixed while testing: the view picker rendered the literal string
"car.tabs.provider" as a row label on an unlinked car. That key does not
exist by design - a linked car's tab is named after the service, an unlinked
one falls back to car.tabs.connected - and the picker was the one caller that
did not know it.
Verified by flutter analyze (clean), flutter test - 19 pass, 7 of them new -
and flutter build apk --debug. The new tests cover what the analyzer cannot
see: the lookups built from a key at render time (car.tabs.$key,
enums.fuelType.$v, the delete dialog's plural counts, the connected service's
readings) are checked to have a real label in all three languages, so a
catalogue entry with no translation fails a test instead of reaching a screen
as a raw key path. That is the check that caught the bug above. A one-off
script also confirmed all 550 static t() keys resolve in en.json.
Not verified: still nothing run against a live API Server or on a device.
Known gaps, deliberately left: admin_users_screen.dart is still English, and
settings.integrations.* / charging.control.* exist in en.json only. The
second one is not the phone's alone - the Web App has exactly the same gap,
so translating that OCPP and connector vocabulary belongs to both apps in one
pass rather than letting the phone run ahead of the app the strings are
copied from. Both are now recorded in TRANSLATIONS.md, which had claimed the
car screen as untranslated and the web app as complete.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
114 lines
5.9 KiB
Markdown
114 lines
5.9 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`), except the Integrations settings and the OCPP
|
|
charger-control card: `settings.integrations.*` and `charging.control.*` exist
|
|
in `en.json` only, so both fall back to English in Polish and Danish.
|
|
- **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`, 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.
|
|
|
|
Still English: **admin users** (`admin_users_screen.dart`), and the same
|
|
`settings.integrations.*` / `charging.control.*` gap the web app has, which is
|
|
worth closing in both at once rather than letting the phone run ahead.
|
|
|
|
`test/models_format_test.dart` guards the lookups the analyzer cannot see —
|
|
the ones built from a key at render time (`car.tabs.$key`,
|
|
`enums.fuelType.$v`, the delete dialog's plural counts, the connected
|
|
service's readings). A catalogue entry with no label fails the test rather
|
|
than reaching a screen as a raw key path.
|