Use the reviewed language contract
Driver App language state combines a locally stored language record, the API client's language, a translation dictionary, source fallbacks, and provider loading. Changing one of those values does not update the others atomically.
This public contract is source-defined. It does not certify the running language service, complete translations, durable persistence, or full right-to-left layout behavior.
Availability
The language provider wraps configuration, session, navigation and task providers, so its loading state can delay downstream startup and background setup. Profile can expose a language selector; the available choices and dictionaries depend on the configured project and current language source.
Prerequisites
- Stable language identifiers and an explicit default-language policy.
- A reviewed dictionary version for Driver App product keys.
- Local persistence that reports success/failure and preserves account/project isolation.
- Fallback copy for every critical control, warning and error.
- Separate review of text direction, layout mirroring, icons, numbers, dates, maps and native/provider UI.
Responsibility boundaries
| Boundary | Responsibility | Limit |
|---|---|---|
| Local language storage | Restore and persist selected ID/code/RTL metadata. | Persistence is not dictionary readiness or server currentness. |
| API client language | Apply the selected code to later source requests. | Client change does not prove service support. |
| Language provider | Load default/stored language, fetch dictionaries, expose loading/error and translate keys. | State transitions and persistence/fetch are not atomic. |
| Translation function | Resolve Driver-prefixed key, original key, fallback, then key text. | Fallback can mask missing/stale dictionary entries. |
| Language selector | Present choices and request a new selection. | Selection UI does not prove persistence or complete refresh. |
| App/task UI | Render translated/fallback strings and re-render from provider state. | Individual screens can retain prior/local state during transitions. |
| RTL metadata | Preserve returned/stored RTL flag. | No reviewed native layout-direction application was found in the Driver App source. |
Inputs and result
| Input/state | Source transition | Result | Partial/failure boundary |
|---|---|---|---|
| Stored language present | Restore record and update API client code. | Provider can begin dictionary refresh. | Stored record/dictionary versions can differ. |
| No stored language | Request configured/default language. | Selected language metadata can be set. | Default-language success can still require later dictionary refresh before loading clears. |
| Dictionary success | Store returned translation map and clear loading. | Translated keys can render. | Missing keys still use fallback/key. |
| Dictionary error/throw | Store empty dictionary or error and clear loading. | Fallback copy can remain usable. | UI can look valid while translation coverage failed. |
| Select different language | Persist metadata, update API client, set loading. | Later effects request translations. | Storage write, client code and dictionary can settle separately. |
| Select current language | No selection change. | Existing state retained. | Does not prove existing dictionary/currentness. |
| RTL language | RTL metadata retained. | Consumers can inspect it. | Native mirroring/direction is not established by this provider alone. |
Security and privacy
- Do not log account tokens, project identifiers or private provider responses while diagnosing language loading.
- Never translate operational identifiers, order values, addresses, phone numbers, coordinates or user-entered content as UI labels.
- Keep fallback strings free of private implementation details.
- Bind late language/dictionary results to the current project and selected language generation.
Limits and failure states
| State | Meaning | Maintainer response |
|---|---|---|
| Language loading | Metadata or dictionary work is unsettled. | Keep downstream readiness explicit. |
| Empty dictionary with rendered text | Fallback/key path is active. | Do not call translation complete. |
| Stored selection but old text | Persistence and dictionary/client state diverged. | Reconcile generation; do not overwrite blindly. |
| Unmount before response | Late transport can return after consumer changes. | Ignore stale generation and avoid state update. |
| RTL flag present | Metadata says language is RTL. | Verify native layout direction separately. |
| Mixed-language screen | Some keys fell back or retained previous render. | Audit key/dictionary/fallback sources independently. |
Troubleshooting
| Symptom | Inspect | Safe diagnostic |
|---|---|---|
| Language change does not persist | Local storage result versus provider state | Use synthetic storage; do not expose project/account data. |
| Some labels remain in the prior language | Selected generation, API client code, dictionary result and fallback keys | Record key category only, not operational values. |
| App remains loading | Language/default/dictionary effect and downstream readiness | Test with intercepted responses; do not use live provider. |
| RTL text appears without mirrored layout | RTL metadata consumers and native direction configuration | Treat as partial support until full platform review. |
| Missing translation is hidden by readable fallback | Dictionary coverage and fallback resolution | Report missing key/locale, not private response payload. |
Re-review whenever language storage shape, dictionary version, key prefixing, default selection, loading/error transitions, selector behavior, RTL consumers or project/account generation changes.
Related guides: Change language · Startup and loading · Driver App architecture · Authenticated bootstrap · Configuration reference