#Internationalization

Note

Q8 is answered — 2026-10-08, backend Phase 1 step 1.10. V8 requirement The oldest open question on this site (raised 2026-10-03) has an owner, a phase and a method: i18n is set up in Phase 1, by Pair 2.

What 1.10 says: every user-facing API text — errors, validation, emails and notifications — comes from lang/ translation keys, never hardcoded English; a middleware reads the Accept-Language header and sets the app language, falling back to English.

It answers the frontend's ask by a different route than proposed, and the difference matters. This site asked for type + params so the frontend could translate. The backend instead translates server-side and returns text already in the user's language. That is simpler for us — a message can be shown as it arrives — but it creates one hard obligation: the request must carry the right Accept-Language, and our server-side calls do not inherit the browser's header. The BFF has to set it explicitly from the locale cookie on every call, including server components. Miss that and every API message silently falls back to English.

Two things are still open: which languages the backend will offer is "decided later", while this site specs eight; and there is still no language field on the profile. See the warning below.

#Rules (project + product)

No locale segment in URLs: /dashboard in every language (Bhavik, 2026-10-05; replaces the old /[locale] project rule). Confirmed
All UI text comes from translation files (messages/<locale>.json). No hard-coded English in components. Confirmed
English is the source: add the key to messages/en.json first. Other locales fall back to English until translated.
Locales: en (default), es, de, fr, pt, ja, ru, hi, all left-to-right. Same set as the OSS panel's locales_available. Confirmed OSS API
Numbers, money, dates, relative times through next-intl (useFormatter, <FormattedX/>). Never toLocaleString().

#URL handling

Locale resolution (no language in the URL)

Requestcookie NEXT_LOCALE set?Yes → use it (if supported)No → Accept-Language supported?Yes → use itNo → en

Paths never contain the language. A shared link (/servers) opens in the reader's own language.
The language switcher is on every page, including the sign-in pages; it sets the cookie, reloads the same page, and (once the profile has a language field) saves it to the profile Missing.
<html lang> follows the locale.

Warning

What is still open after 1.10: the language list. Open question The backend will translate its texts, but which languages it offers is "decided later" — and this site specs eight (en, es, de, fr, pt, ja, ru, hi), matching the OSS panel. If the backend ships fewer, a user who picks an unsupported language gets our UI translated and the backend's messages in English — a half-translated screen, which is worse than a consistently English one.

So the language switcher should offer what both sides support, not what the frontend alone can render. Until the backend's list is published, keep mapping known error codes to frontend keys where one exists: that keeps the common messages right in all eight regardless of what the backend decides.

Also still missing: a language field on the profile Missing, so the choice lives only in a cookie and does not follow the user to another browser.

#Backend messages

Send Accept-Language: <locale> on every API call, so Laravel validation and error messages come back translated. Confirmed 2026-10-08 (1.10): a middleware reads the header and sets the language, falling back to English V8 requirement. The BFF must set this header itself — a server-side fetch carries no browser headers, so read the locale cookie and attach it on every call, or everything arrives in English.
Forward the same header to OSS. OSS already localises its message fields. OSS API
Prefer codes in API errors (code: "PLAN_LIMIT_REACHED") mapped to frontend keys, with the backend message as a fallback.
Audit and notification entries carry action/type keys + params, so they render in the viewer's language (V7 stored English sentences).

#Missing translations

In development: log a warning naming the missing key, and render the English text.
In production: silent fallback to English, no raw key shown.
CI check: every key in en.json exists in each locale file (allowed to equal English), and there are no unused keys Assumption.

#Content not translated

User data (server names, organization names, member names), raw OSS output (logs, command output), and plan names unless the API provides translations Open question.