# Frontend translation

## Bricks Technical Documentation

*How the Bricks web app resolves a language, where its translations live, and how localized tenant content (media, labels) is kept separate from the app's own interface strings.*

---

Bricks ships a single web application that speaks fifty-two languages out of the box. Everything is resolved **once, on the server, per request**, and handed to the page. That is what avoids the "flash of English" you see on many localized single-page apps.

There are two entirely separate axes of language, and confusing them is the single most common mistake:

- **Interface chrome** — buttons, menus, headings, system messages. A fixed set of strings shipped with the app.
- **Tenant content** — media titles, document bodies, entity labels, role names. Data that comes from the API and carries its *own* per-language versions.

A Korean user can read a French-only document inside a fully Korean interface. The two never merge.

## Supported languages

The language picker offers fifty-two languages, with **English as the reference language** — every key exists in English first, and any missing translation falls back to English rather than showing a blank or a raw key.

`ar` · `az` · `bg` · `bn` · `bs` · `cs` · `da` · `de` · `el` · `en` · `es` · `et` · `fi` · `fr` · `hi` · `hr` · `hu` · `hy` · `id` · `is` · `it` · `ja` · `ka` · `kk` · `ko` · `ky` · `lb` · `lt` · `lv` · `mk` · `nl` · `no` · `pl` · `pt-br` · `pt-pt` · `ro` · `sk` · `sl` · `sq` · `sr` · `sr-latn` · `sv` · `tg` · `th` · `tk` · `tr` · `uk` · `uz` · `uz-cyrl` · `vi` · `zh` · `zh-tw`

- **Two scripts for one language.** Serbian is offered in Cyrillic (`sr`) and Latin (`sr-latn`), Uzbek in Latin (`uz`) and Cyrillic (`uz-cyrl`); the second script is generated from the first, so the two always say the same thing.
- **Right-to-left.** Arabic renders the whole page right-to-left.
- **Review status.** Every bundle is checked for complete key coverage, valid placeholders and correct quotation marks before it ships. Some translations were drafted by AI and have not yet been reviewed by a native speaker.
- **Unfinished translations are never served.** A language still being translated is unreachable by every path — picker, cookie, browser header or URL — until it is complete.

## How a language is chosen

On every request the server resolves the active locale from the first source that yields a supported language, in this priority order:

```mermaid
flowchart TD
    A["Request arrives"] --> B{"URL param<br/>?ui_locales / ?lang"}
    B -- match --> Z["Use it"]
    B -- none --> C{"Signed-in account<br/>language preference"}
    C -- supported --> Z
    C -- none --> D{"bricks_locale cookie"}
    D -- supported --> Z
    D -- none --> E{"Accept-Language header<br/>(exact tag, then base language)"}
    E -- match --> Z
    E -- none --> F["Default: English"]
    Z --> G["Page rendered server-side<br/>in the resolved language"]
```

Each source is tried as an exact tag first, then as its base language — so `fr-CA` resolves to `fr`. The URL parameter exists so that a tenant app redirecting a user to the hosted Bricks sign-in screen can pin that screen's language.

### Persistence across devices

When a user picks a language:

1. A one-year `bricks_locale` cookie is written, so anonymous visitors keep their choice.
2. If the user is signed in, the choice is promoted to the top of their Bricks account's language list — so it follows them across every Bricks app and every device.
3. The page reloads, producing a fresh server render in the new language.

Language switching is a full reload by design, not a reactive in-place swap. This keeps the server as the single source of truth for what language a page is in.

## Fallback within a language

Missing keys never break the page. The server merges the active locale *over* English before the page ever renders, so any key absent from, say, Polish silently resolves to its English string:

```mermaid
flowchart LR
    K["Interface needs a string"] --> M{"Key in active locale?"}
    M -- yes --> V1["Localized string"]
    M -- no --> EN{"Key in English?"}
    EN -- yes --> V2["English string"]
    EN -- no --> KEY["Raw key<br/>(caught in review before release)"]
```

## Tenant content is a different system

Interface strings are fixed and shipped with the app. **Tenant content** — anything a tenant creates — carries its own translations and is resolved differently.

- **Media** (documents, images, videos in a tenant's library) can hold **multiple language versions**, each with its own title, description and body. The media viewer picks a primary version — your interface language if it exists, otherwise English, otherwise the first available — and offers **language tabs** so you can switch the *content* language independently of the interface. This very document is published that way: one logical media item, an English and a French version, shown as tabs.
- **Entity labels and role names** arrive from the API as small objects keyed by language, e.g. `{ "en": "Customer", "fr": "Client" }`. The app resolves them with the same "your language → English → first available" rule. System roles use a shipped interface key; custom tenant roles fall back to the tenant's own stored label — the presence of an interface key is what distinguishes the two.

The practical consequence: **your interface language and the language of the data you are looking at are independent.** Localizing the interface into a new language does not translate any tenant's data, and vice versa.

---

*This page describes shipped behavior of the Bricks web application. It is companion reading to [Backend translation](/technical/backend-translation), which covers how the API, emails and stored tenant data are localized on the server side.*
