tajniak81andClaude Opus 5
a7cab50e06
Apprise is a Python library that speaks 100+ notification services behind one URL grammar — mailto://, tgram://, ntfy://, discord://. None of that is portable to a server that takes no dependencies, and none of it needs to be: caronc/apprise-api wraps the library in HTTP and is meant to run as a container beside us. So the connector carries no notification protocols of its own. It posts a body to an endpoint the operator runs and lets Apprise fan it out, which is also why adding a service later costs nothing here. Targets are addressed one of two ways and configKey is the switch. Stateful means the URLs live on the Apprise server under a key, narrowed by a tag expression, and recipients are then edited there — no credential for any downstream service is ever held in DriverVault. Stateless means the URLs travel with the request, from a secret config field, which is simpler for one destination and worse for ten. A call that names its own key or urls takes that destination alone rather than merging with the configured one: honouring a caller's URLs while still falling back to the configured key would deliver the message somewhere nobody asked for. baseUrl is Required, which no other connector's address is. Toyota, Anker and Greencell leave everything blank at the global layer because the superadmin → org → user cascade exists to fill it in, and a blank there means "let the user choose". There is no cascade behind this one — a notification gateway is infrastructure the operator runs, not an account a driver owns — so nothing further down can supply the address, and a blank is simply a plugin that cannot work. Better to fail at enable than at the first notification nobody sees. Three limits are choices rather than gaps. /add and /del are not implemented: the Apprise config belongs to the operator, we post to it, and a connector that can delete a notification config has a wider blast radius than one that can only send through it. privacy=1 is forced on /json/urls rather than offered as a parameter, so a target listing reads mailto://user:****@host and downstream tokens stay on the Apprise side of the wire. Attachments are remote URLs the Apprise server fetches; multipart upload is the API's own path for files and not ours. Health follows the rule Greencell set. A reachable server whose config holds nothing to notify is degraded, not down: the half we address works and the missing half is the operator's config. Two cases earn their own line — a config key set against a server running with stateful mode disabled can never resolve, and /status answers 417 rather than 500 when Apprise finds a problem with itself, so that is a parsed answer and not a transport failure. A proxy that strips our Accept header gets the same codes back as plain text, which is read rather than called unreadable; an HTML error page from something that is not Apprise is not, and a test pins the difference. Notifications needed a category of their own, and that is the one change outside the plugin: the constant, the tab order in PluginsCard.vue, and the label in all three panel languages. The cost is now written down in the plugins README beside the Descriptor example, since the previous five categories predate anyone having to add a sixth. The plugin's tests run against an apprise-api stand-in built from that project's views.py — both notify paths, the override rules, 204-as-empty against 424-as-failure, and every health branch. builtin_test.go is the other half: the blank-import list in builtin.go is a silent failure mode, since a connector left out of it compiles, passes its own tests, and never appears in the panel. What is not covered is a live instance; there is no Docker on this machine, so the wire contract comes from reading upstream's source rather than from running it, and a smoke test against a real deployment is still worth doing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
129 lines
7.0 KiB
Markdown
129 lines
7.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`) |
|
|
| **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, MQTT, MQTTS, TLS, Toyota Connected, MyToyota, Anker Solix, Greencell,
|
|
HabuDen, Lexus, Apprise) read the same in every file, as do the units — and so does the
|
|
Greencell device command `QUERY`, which is a literal the charger listens for.
|
|
|
|
- **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.
|