tajniak81andClaude Opus 5
12ec10a797
The web app can be pointed at two DriverVault stacks and switch between them in a click. The phone had one address and one session: reaching a second garage meant retyping the API base in Server settings and signing in again, losing the first server's token on the way — the same act, undone, every time you switched back. So lib/servers.dart is the web's servers.js ported rather than reinvented, down to the storage keys: cc_servers holds the list, cc_active_server the one being read, cc_session_<id> the token minted by that server and no other. The two apps describe the same thing the same way, and the upgrade path falls out of it — cc_token, cc_user and cc_server_url are read once at boot and folded onto the home entry, so the build carrying this signs nobody out. Home is the address the build ships with (kDefaultApiBase, still overridable per device from the login screen) and cannot be removed: it is what a dropped session falls back to. Any other server is added by address, with /api appended if the path is left off, because a server a phone can reach is internet-facing already. The part worth reading twice is which session a rejection ends. ApiClient no longer holds a base or a token — it pins the active server's id, base and token at the moment a request goes out, so a 401 arriving after a switch clears the session of the server that actually refused it rather than whichever one is active by then. The fallback is the web's: a remote server timing out drops its own token, the app returns to home while home is still signed in, and only when nothing is left to fall back to does the login screen come back. Log out still clears every server at once, since leaving the app means leaving all of them. Switching rebuilds the shell, keyed on the active id, because record ids belong to the server that issued them — a garage, a charging page and a settings panel still holding the other server's rows would each have to be told to forget them separately. The appearance prefs come across with the profile of whoever owns the account on the server now active. Where the picker lives is the one place the phone cannot copy the web. There is no app rail here, so it became the first button in the Garage header, beside the theme toggle and log out, which is that same cluster. It names the active server once there is a choice and goes straight to adding the second when there isn't; the eyebrow reads GARAGE · Work for the reason the rail names it — two garages otherwise look identical. The login screen gets its own way in, because a remote session can expire and land you there with that server still active, and a picker reachable only from inside the app would leave nowhere to go. One judgment call inside the sheet: saving a connected server at a new address saves and stops, rather than falling through to the sign-in it now needs. The token was minted by the PocketBase behind the old address and is dropped with it, but the credentials to replace it were never asked for, so treating the save as a login would report an empty password as the error. The strings are copied out of Web App/web/src/i18n/ like the rest of the shared wording. Two are not the web's: home reads "the address this app ships with" rather than "served with this app", since the phone has no origin to be served from, and sameOrigin has no meaning here at all and was dropped. Biometric sign-in stays global. It was never per-server and replays its stored credentials against whichever server is active; making it per-server is a change of its own, and the login screen now names the server it is about to sign into. Nothing changes on the API Server. On Android there is no origin to allow, so the CORS list the web app has to satisfy to reach a second server doesn't enter into it. Verified: flutter analyze is clean and flutter test passes, 35 tests to 46. The new ones cover the registry — a bare origin gaining its /api, a fresh install knowing one unnamed server on the built-in address, the legacy keys landing on home and being cleared, two servers holding their tokens apart, a rename keeping a session where a move drops it, removing the active server falling back to a home that is still signed in, home refusing to be removed, and a restart reading the list, the active id and every session back. Not verified: none of it has been run. There is no device or emulator on this machine and no API Server to answer, so the picker, the add sheet, a real connect, the 401 fallback and the shell rebuild on a switch exist only as code the analyzer is happy with — the tests reach the registry, not a screen. No APK was built. The legacy migration was exercised against mocked SharedPreferences, which is not a phone that had the old build on it: that is the first thing to check on a device, since the failure mode is a silent sign-out. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
118 lines
6.1 KiB
Markdown
118 lines
6.1 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 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.
|
|
|
|
`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.
|