Skip to content
All technical docs Bricks technical documentation

Backend translation

How the Bricks API localizes what it produces — assistant messages, emails and stored tenant data — and why the language of a response can come from three different places depending on what is being translated.

Backend translation

Bricks Technical Documentation

How the Bricks API localizes what it produces — assistant messages, emails and stored tenant data — and why the language of a response can come from three different places depending on what is being translated.


Backend translation on Bricks is not one system but several, each fit to a different surface. Understanding which mechanism applies matters because the language of a backend response is chosen differently depending on what it is — a request header for one, a stored account preference for another, an explicit query parameter for a third. There is no single global language negotiation, and that is intentional: an email and an inline assistant message have genuinely different notions of "which language."

The three server-rendered surfaces

1. Assistant and system messages — from the request

Runtime messages produced by Studio AI and platform flows (things like "your balance is low", "the assistant is still working", onboarding hints) are translated on the server from the request's Accept-Language header.

The language is resolved once when the request arrives — parsed with quality-weights, matched against the supported languages, defaulting to English — and then carried through the entire request, including long assistant turns that await many times. This per-request isolation is deliberate: a shared variable would let one user's concurrent request overwrite the language another turn is about to read, leaking the wrong language into a response. The fallback chain is: requested language → English → the key itself.

2. API errors — English on the wire, translated by the client

API error responses are not translated on the server. An error carries three things:

  • a human-readable English message, always safe to show,
  • a stable machine-readable code,
  • an optional translation pointer (i18n: { key, vars }).

The web app resolves that pointer against its own language bundle and falls back to the English message when no translation exists. This lets the API ship a new error shape before its translations are written, without a coordinated deploy. Server errors (5xx) are scrubbed to a generic message unless explicitly marked safe to expose.

3. Emails — from the recipient's stored language

Transactional emails (invitations, password resets, sign-up confirmations) are fully rendered on the server from per-language templates. The language is never taken from a request header — it comes from the recipient's Bricks account languages: their ordered list, in order of preference, and the first one the email exists in wins. When the recipient has no list, or none of their languages has a template, the language passed by the caller applies, then English. An invitation to someone who set their account to Korean arrives in Korean regardless of who triggered the send or from what browser.

mermaid diagram

Translating tenant data

Content that tenants create and that must display in multiple languages — a tenant's display name, an entity's label, a role's description — is stored as a small object keyed by language:

{ "en": "Customer", "fr": "Client" }

When read back, the value resolves to your language, then English, then the first available translation, then falls back gracefully. Technical identifiers, personal names, enum codes and ISO codes are deliberately left as plain text — they are not translatable and wrapping them would only add noise.

Media carries language as a first-class field

Tenant media takes a different, simpler approach: each media translation is a separate stored item tagged with a free-form language. This is why a single logical document can hold an English and a French version side by side, surfaced as language tabs in the media viewer. See Frontend translation for the reader's side of this.

Relationship labels resolve at read time

When one record points at another (a foreign-key relationship), Bricks shows a human-readable label for the target rather than a raw id. How that label is built is configurable per relationship, and the display language is passed as a ?locale= query parameter when reading records — a third distinct language source.

When a relationship has no explicit label configuration, Bricks derives one at read time, trying a sensible precedence of columns:

mermaid diagram

The important behavior: a relationship created after labels were configured elsewhere still renders a readable chip instead of a bare id, because the derivation runs whenever no explicit configuration is present.

One rule to remember

Translatable tenant fields must be stored as a JSON object, never as a JSON string that happens to contain an object. A double-encoded value (a string like "{\"fr\":…}") looks correct at a glance but breaks every reader — it renders as escaped JSON, and per-language extraction errors out. The platform guards its own tables against this and heals tenant data when it is detected, but if you write translatable fields through the data API directly, write a real object.

Where each surface gets its language

Surface Language comes from
Assistant / system messages Accept-Language request header
API errors Not translated on the server — the web app translates the pointer
Emails Recipient's stored account language
Entity / relationship labels ?locale= query parameter
Tenant display names, descriptions Resolved from the stored per-language object

This page describes shipped behavior of the Bricks API. Its companion, Frontend translation, covers how the web app chooses a language and renders localized content.