--- title: "Driver App language contract" description: "Understand language persistence, dictionaries, fallback behavior, loading, and RTL support." canonical: https://docs.ordering.co/docs/developers/driver-app/language-contract/ --- # Driver App 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. The visible language, loaded translations, saved preference, and layout direction can update separately. Translation availability depends on project configuration. ## 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 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. - Check 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. | The Driver App provider does not apply native layout direction from this flag. | ## Inputs and result | Input/state | 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. | Check key, dictionary, and fallback behavior separately. | ## 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 | RTL metadata alone does not enable full layout mirroring. | | Missing translation is hidden by readable fallback | Dictionary coverage and fallback resolution | Report missing key/locale, not private response payload. | Revisit this contract 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](https://docs.ordering.co/docs/products/driver-app/account/language/) · [Startup and loading](https://docs.ordering.co/docs/products/driver-app/get-started/startup/) · [Driver App architecture](https://docs.ordering.co/docs/developers/driver-app/architecture/) · [Authenticated bootstrap](https://docs.ordering.co/docs/developers/driver-app/authenticated-bootstrap/) · [Configuration reference](https://docs.ordering.co/docs/developers/driver-app/configuration-reference/)