> ## Documentation Index
> Fetch the complete documentation index at: https://twenty-c--pull-3-cli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Translations

> Ship your app in multiple languages — translate manifest labels and UI strings through one locales catalog.

Twenty apps are authored in **English**: the strings in your source and manifest
are the English source text, `en` is the source locale you translate *from*, and
any locale left untranslated falls back to it.

Your app has two kinds of translatable text, and both flow through the same
`locales/` catalog:

* **Manifest labels** — object and field names, view titles, menu items, and
  other strings declared in your app's metadata.
* **Front-component strings** — the UI text your React front components render.

You mark the translatable strings, extract them into per-locale catalogs,
translate those catalogs, and the build serves the right language for the
current user — no extra wiring.

## Marking front-component strings

Import the translation helpers from `twenty-sdk/front-component`:

```tsx theme={null}
import { Trans, t, msg, useTranslate } from 'twenty-sdk/front-component';

const STATUSES = [
  { id: 'draft', label: msg('Draft') },
  { id: 'sent', label: msg('Sent') },
];

const Card = ({ count, name }: { count: number; name: string }) => {
  const { t } = useTranslate();

  return (
    <section>
      {/* Static text — reactive to the user's locale */}
      <Trans>Loading postcard…</Trans>

      {/* Disambiguate identical sources with a context */}
      <Trans context="card-title">Untitled</Trans>

      {/* Interpolation: pass values explicitly */}
      <p>{t('Hi {name}', { name })}</p>
      <p>{t('Saved {count} cards', { count })}</p>

      {/* Resolve a lazily-declared descriptor */}
      <ul>{STATUSES.map((s) => <li key={s.id}>{t(s.label)}</li>)}</ul>
    </section>
  );
};
```

### When to use which

* **`Trans`** — static text in JSX. Use the `message` and `values` props for
  interpolation, as in `Trans message="Hi {name}" values={{ name }}`;
  interpolating directly in the children is not statically extractable.
* **`useTranslate().t`** — dynamic strings inside a component. Re-renders when the
  user switches language. Prefer this inside render.
* **`t(...)`** (imported directly) — eager translation usable **anywhere**,
  including event handlers, helpers, and module scope — not only inside render.
* **`msg(...)`** — a lazy descriptor for strings declared as data (constants,
  config). Resolve it later with `t(descriptor)`.

### Context

Pass `context` to disambiguate identical source strings that translate
differently:

```tsx theme={null}
t({ message: 'Open', context: 'door' });
t({ message: 'Open', context: 'window' });
<Trans context="card-title">Untitled</Trans>
```

Contextual strings appear in locale catalogs as a group keyed by their
context: `"<context>": { "<message>": "<translation>" }`. Manifest labels are
contextual by construction — each one carries the metadata role it plays
(`objectMetadata.labelSingular`, `fieldMetadata.label`, `view.name`, …), so
the same word can translate differently as an object name and as a view name.

## Extracting and translating

Run the extract command from your app directory:

```bash theme={null}
twenty dev:translations-extract                  # collect strings into locales/en.json
twenty dev:translations-extract --locale fr-FR   # also scaffold a target locale
```

Extraction collects both your manifest labels and the `t()`/`msg()`/`Trans`
strings from your front-component source into `locales/<locale>.json`, keyed by
source string. Fill in the translations:

```json theme={null}
// locales/fr-FR.json
{
  "Loading postcard…": "Chargement de la carte…",
  "Hi {name}": "Bonjour {name}",
  "Saved {count} cards": "{count} cartes enregistrées",
  "door": {
    "Open": "Ouvrir"
  },
  "objectMetadata.labelSingular": {
    "Postcard": "Carte postale"
  }
}
```

Context-free strings are flat entries; contextual strings — including every
manifest label — are nested under their context key.

Placeholders like `{name}` are substituted at runtime — keep them in the
translation. Any string left empty falls back to the source text.

## How it runs

`twenty dev:build` compiles the catalogs and serves the right language for the
current user: manifest labels are resolved server-side, and front-component
catalogs are baked into each component bundle. At runtime a component reads the
locale from its execution context (the host's current language) and resolves
each string against its catalog, falling back to the source when a translation
is missing. Switching language in the host re-renders `Trans` and
`useTranslate().t` strings live.

Manifest labels are compiled on every sync — `twenty dev:build`, `twenty apply`
and the continuous `twenty dev` watch alike — so editing a locale file and
syncing is enough to see the new text. Front component catalogs are baked into
each component bundle at build time, so changing one of those still means
re-running `twenty dev:build` (and redeploying).

`Trans` text children may span multiple lines — whitespace is collapsed the
same way JSX collapses it, so both of these extract to the key `Welcome back`:

```tsx theme={null}
<Trans>Welcome back</Trans>
<Trans>
  Welcome
  back
</Trans>
```