tajniak81andClaude Opus 5
a203414ceb
The one place a service badge is worth reading is the car it belongs to, and that is the one place the app could not be opened: Android Auto runs no Flutter engine, so a Flutter app is simply absent from the head unit. The same APK now carries a second face — Car App Library templates the host draws itself, in Kotlin under android/app/src/main/kotlin/com/drivervault/phoneapp/car/. Two screens. The garage lists a car per row with its due badge on the second line, worst first, because the host renders only the first handful of rows and the car this list exists to mention is the overdue one rather than whichever was added first. A tap opens what that car has coming: the odometer, the next service, and the reminders the server holds for it — typed in and auto-derived from documents and the service schedule alike, in the order it sorted them. None of it is a second implementation of the app. VaultStore reads the session the phone signed in with — the active server's base and token — out of shared_preferences' own store, which both halves share, so a server switched on the phone is the server the car reads from with nothing to keep in step; only cc_active_base is new, because an untouched home entry carries no address of its own, its base being kDefaultApiBase, a compile-time define nothing outside Dart can see. CarStrings reads the same assets/i18n files by the same dot paths, so a badge on the head unit is the string format.dart already puts on the phone, in the language the account chose: of the 32 keys the car screens ask for, 28 are keys a phone screen already used, and only carApp.* is theirs. CarFormat is format.dart's twin — same date pattern and number grouping from the account's settings, same worst-of-date-and-km service badge. A new test reads the Kotlin for the keys it looks up and fails if any is missing from a language file, since the analyzer's reach stops at the Dart. It only reads. A screen you cannot type into is a poor place to edit a car and a driver is a poor person to ask, so VaultApi has no write in it to reach for by accident. Three things the README now says out loud. The service is declared IOT, the closest category the library defines for something that is a garage rather than a map or a media player, which matters to a store submission and not to a sideload. The app lock does not reach the head unit: the flag is in memory and the credentials behind it in encrypted storage, neither readable from the car service, and there is no fingerprint reader in a dashboard to satisfy it with. And the home charger is not on there — the chargers endpoint relays its plugin's payload verbatim with no shape to read, and the serial the control card is driven by is never persisted, so the car would have nothing to name. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
128 lines
6.9 KiB
Markdown
128 lines
6.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`) |
|
|
| **Phone App — Android Auto** (Kotlin) | the same files, read out of the APK's `flutter_assets/` | `Phone App/android/…/phoneapp/car/CarStrings.kt` | the same profile `locale`, read from shared_preferences |
|
|
|
|
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 server picker
|
|
and its add/sign-in sheet, 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.
|
|
|
|
The **Android Auto** screens read those very files again, by the same keys, out
|
|
of the APK — the car has no Flutter engine to run `i18n.dart` in, so
|
|
`car/CarStrings.kt` does the same lookup over the same JSON. Almost everything
|
|
it asks for is a key a phone screen already uses, the status badges included;
|
|
only `carApp.*` (four strings — nobody signed in, token refused, server
|
|
unreachable, Refresh) is the car's own. Plurals are the one part it leaves out:
|
|
no car screen needs one, and a plural key comes back as the key, which is what
|
|
`i18n.dart` does with one it cannot render either.
|
|
|
|
`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, the Service history columns and the parts a service can change) 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.
|