# 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.