Localization

Rakomi ships with five GA locales out of the box: English, Polish, German, French, and Spanish. Every authentication surface uses the same resolution rules so an end-user sees the same language across login, sign-up, verification, MFA, and error screens.

Resolution precedence

Hosted sign-in (accounts.rakomi.com)

Locale is picked by the first non-empty rule in this order:

1. URL path prefix — /{locale}/...
2. OpenID Connect ui_locales query parameter — first supported value wins
3. NEXT_LOCALE cookie — set when the end-user clicks the language switcher
4. The tenant’s default language configured in the dashboard
5. The browser’s Accept-Language header (RFC 4647 lookup)
6. en (hard default)

React SDK (@rakomi/react)

The <RakomiProvider> picks the effective locale from:

1. Explicit <RakomiProvider locale="..."> prop
2. Tenant default from the public tenant-config endpoint
3. navigator.language mapped to the nearest supported locale
4. en (hard default)

API (JSON error responses)

1. Accept-Language header (RFC 4647 lookup against the five GA locales)
2. Authenticated tenant default
3. en (hard default)

Every non-OAuth JSON response echoes the resolved locale via Content-Language and adds Vary: Accept-Language, Cookie for shared-cache safety.

Error-message contract

User-facing errors carry a machine-readable code (stable, English message) and an optional message_localized in the resolved locale.

{
  "error": {
    "code": "auth/invalid_credentials",
    "message": "Invalid email or password.",
    "message_localized": "Ungültige E-Mail-Adresse oder Passwort."
  }
}

Clients MUST fall back to message if message_localized is absent — for example, when a rare error has not yet been translated or the request’s locale falls outside the GA set. error.message is always English; it is never substituted.

OAuth 2.0 endpoints (/oauth/*) follow RFC 6749 strictly: the error and error_description fields remain in English, and message_localized is not added. The visual consent screen rendered by the hosted app is still localized.

Setting the tenant default

In the Rakomi Dashboard, open Settings → Tenant → Default language. Choose one of the five locales or leave it on Auto-detect to let the browser decide. Changing the tenant default does not retroactively re-language active sessions — end-users keep their current preference.

Overriding UI strings in your app

The React SDK accepts a translations prop on <RakomiProvider>. Provide a partial object — missing keys fall back to the locale dictionary, then to English.

<RakomiProvider
  clientId="pk_..."
  locale="en"
  translations={{
    'signIn.title': 'Welcome back',
    'signIn.submitButton': 'Let me in',
  }}
>
  <SignIn />
</RakomiProvider>

What is not yet localized

• Operator dashboard — the admin tool is English and Polish only.
• Transactional emails (verification, password reset) — English and Polish only.
• Status page and landing page — handled on a separate roadmap.
• Right-to-left scripts (Arabic, Hebrew) — future roadmap.

Translation quality

Initial non-English translations are produced with AI assistance and reviewed against a product glossary that pins the canonical form of critical terms (passkey, MFA, recovery code, etc.). Translation files are version-controlled so every change lands in a pull request with the usual review process; the build rejects files that drift out of sync, miss placeholders, or contain unsafe markup. If you spot a copy issue as an end-user, please report it — corrections are rolled into the next release.