public-api-docs

User API Localization Guide

Overview

The User API exposes localized message resources for operator-built white-label apps. These resources let the app reuse the same localization keys that are already configured in the platform and add app-specific keys for custom screens, labels, buttons, empty states, tutorials, notifications, or feature text.

Use localization resources when the app needs tenant-managed copy instead of hard-coded strings. The User API reads localized resources. Creating, updating, importing, or deleting message-resource keys is an Operations API/admin task.

Related reference: User API

User API Guide

Tutorial Guide

Core Concepts

Message Resource Keys

A message resource is identified by a stable key, also called a localization key. The key is what the app references in code; the value is the translated text returned for a locale.

Example:

app.wallet.empty.title
app.wallet.empty.description
app.rental.end.photo_required
app.voucher.free_unlock

Use stable, namespaced keys for app-owned copy. A good convention is to prefix app keys with the product area, for example app.rental.*, app.wallet.*, app.payment.*, or app.tutorial.*.

Areas

Message resources are organized by area. For the User API app endpoint, the platform exposes app-relevant resources:

Area	Use
`APP`	Mobile/web customer app copy. Use this for operator app-specific strings.
`SHARED`	Copy shared across app surfaces and platform flows.

Dashboard and core-only resources are not the primary source for the user app. When adding custom app strings, create them in APP unless they intentionally need to be reused across multiple platform surfaces.

Locale

The app requests localized resources for a locale:

GET /resources/messages?locale=en
GET /resources/messages?locale=de

Use GET /resources/messages/languages to list locales that have message resources available for the app.

Common User App Workflow

Bootstrap App Copy

Load localized resources during app startup or when the user changes app language:

GET /resources/messages?locale=en

The response is a map keyed by localization key. In User API frontend responses, the message resource object exposes the translated value.

Example response shape:

{
  "app.wallet.empty.title": {
    "value": "No wallet credit yet"
  },
  "app.rental.end.photo_required": {
    "value": "Please upload a parking photo before ending your trip."
  }
}

In the app, normalize this into a simple key-value dictionary:

messages["app.wallet.empty.title"] = response["app.wallet.empty.title"].value

Use Existing And Custom Keys

Apps can use:

platform keys that already exist for common flows,
operator-created custom keys for white-label app screens,
tutorial slide translation keys where the tutorial payload provides them,
localized messages returned directly by flow endpoints, such as rental requirement message.

Prefer API-returned user-facing messages when an endpoint already returns a localized message, because that message is tied to the exact backend rule that failed. Use message resources for static or semi-static app copy that the app controls.

Fallback Strategy

Implement a fallback order in the app:

Try the user’s selected locale.
Fall back to the operator’s default locale.
Fall back to English or the app-bundled default string.
Log missing keys in the app so operators know which translations to add.

Do not block core app flows because one optional localization key is missing. Use a safe fallback string and continue.

Caching

Message resources are good cache material. Load them at startup and cache by locale. Refresh them when:

the user changes language,
the app version changes,
the user signs into a different tenant/branch context,
the app receives a manual refresh signal,
the cache is older than the app’s configured TTL.

Use available languages from GET /resources/messages/languages to populate language selectors or validate the language chosen by the user.

Managing Keys

The User API reads localization resources. Operators manage keys through Operations API/admin tooling:

Management task	API surface
Create a new key and translation	Operations message-resource management
Update an existing translation	Operations message-resource management
Import many translations	Operations CSV import for message resources
Review missing translations	Operations message-resource management
Read app translations in the app	User API `GET /resources/messages`

When adding custom keys for a white-label app:

Choose a stable key name.
Add translations for every supported locale.
Put app strings in the APP area unless they are intentionally shared.
Release the app with the key name, not with the translated value hard-coded.
Keep fallback copy in the app for resilience.

Most Relevant APIs

Area	Endpoints
App message resources	`GET /resources/messages`
Available languages	`GET /resources/messages/languages`
Tutorials using localized content	`GET /tutorials`
Runtime localized flow messages	`GET /rentals/requirements`, end-rental check endpoints, and other flow-specific responses that include `message`

Implementation Notes

Treat localization keys as stable contracts between the app and the platform content configuration.
Use APP keys for white-label app copy and SHARED keys for copy intentionally reused across surfaces.
Cache message resources per locale, but make refresh possible without shipping a new app build.
Do not hard-code backend error or requirement copy in the app when the API already returns a localized message.
Keep app fallback strings for missing keys so localization gaps do not break critical flows.