# Languages and translations

> Declare languages, translate per field or per document, read one language with a fallback, find missing and outdated translations, limit translators to their language, let agents translate on a branch, and route languages in Next.js.

A project declares its languages once. Each type then picks how it is translated: per field, with every language in one document, or per document, with one document for each language. Delivery returns one language at a time, with a fallback to the default language, and the content checks list what is missing or out of date.

## Declare the languages

```ts
export default defineConfig({
  languages: ['en', 'fr', 'de'],
  types: { /* … */ },
})
```

The first language is the default. It is the one `required` fields must fill, and the one delivery falls back to. Codes look like `en`, `fr` or `pt-BR`. Removing a language is a breaking change for `galerne schema deploy`.

## Translate per field

Mark fields `localized: true`. One document holds every language:

```ts
page: {
  fields: {
    title: { type: 'string', localized: true, required: true },
    body: { type: 'richText', localized: true },
    hero: { type: 'image' },
  },
},
```

```json
{ "title": { "en": "Harbours", "fr": "Ports", "de": "Häfen" }, "hero": { "asset": "m_7Qk2…" } }
```

Paths reach one language: `patch_doc` with `{ "set": { "title.de": "Häfen" } }` changes only the German title. This fits pages that keep the same structure and images in every language.

## Translate per document

Set `i18n: 'doc'` on the type. Each language is its own document, with `_lang` and, for translations, `_translationOf` pointing to the source:

```ts
post: { i18n: 'doc', fields: { title: { type: 'string', required: true }, slug: { type: 'slug', from: 'title' }, body: { type: 'richText' } } },
```

```json
{ "branch": "agent/translate-de", "type": "post", "id": "harbours-de", "lang": "de", "translationOf": "harbours", "values": { "title": "Häfen der Bretagne", "slug": "haefen-der-bretagne" } }
```

That is the input of `create_doc`. Each translation has its own slug, drafts, publish state and history, so a German post can go live a week after the English one. In the studio, the **translations** panel of a document lists its languages, opens each one, and flags translations whose source changed after them. Slugs are unique per type and language.

You can mix both models in one project: localized fields on `page`, documents per language on `post`.

## Read one language

Pass `lang` to the [query API](/docs/query.md#languages). Localized fields collapse to their value in that language, and types with documents per language return only that language's documents. `fallback: true` fills the gaps from the default language.

```bash
curl https://api.galerne.cloud/p/acme/v1/query \
  -H 'content-type: application/json' \
  -d '{"type":"post","lang":"de","fallback":true,"perspective":"published","order":"-_publishedAt"}'
```

Filter on one language of a localized field with its path: `{ "where": { "title.fr": { "exists": false } } }` finds pages with no French title.

## Find what is missing

The content checks report two warnings for translations:

| Check | When |
|---|---|
| `missing-translation` | A localized field is empty in a language, or a document has no translation in a language |
| `outdated-translation` | The source document changed after the translation was last edited |

`check` returns them for one document, a type or a whole branch, and the review of a branch lists them. Agents use them as a to-do list:

```json
{ "branch": "agent/translate-de", "type": "post" }
```

## Translators and their language

On the Business plan, each member can be limited to some languages in **Settings**, **Members**. A German editor limited to `de` writes localized values in German and documents whose `_lang` is `de`, and nothing else. Reading and commenting stay open. Agents take the same limit. See [limits per member](/docs/agents.md#limits-per-member).

## Agents that translate

The MCP server ships a `translate_doc` prompt. It tells the agent to read the schema and the guidelines, translate on a branch named `agent/translate-<language>`, use the glossary of the [guidelines](/docs/schema.md#the-guidelines-type) for terms, keep links, references and media as they are, run `check`, and ask for review. In Claude, it shows in the prompts menu of the connector, with the document id and the language as arguments. The agent runs it with its own model.

A person then reads the field diff in the review, comments where a term is wrong, and promotes the branch.

## Languages on the site

The [Next.js kit](/docs/nextjs.md#languages) follows the document-per-language model. `createI18nProxy` sends readers to their language, `galerne.bySlug(type, slug, lang)` finds the document with a fallback or a redirect, `galerne.alternates(doc, lang)` writes the hreflang links, and `galerne.strings(lang)` reads UI strings from a `strings` singleton that editors translate in the studio.

```ts
// proxy.ts
import { createI18nProxy } from '@galerne/next/proxy'

export const proxy = createI18nProxy({ languages: ['en', 'fr', 'de'], defaultLanguage: 'en' })
```

Imports from Sanity, Contentful, Storyblok, Payload and Markdown keep their translations, as localized fields or documents per language. WordPress translation plugins are not read: each translation comes in as its own post. See [migrating](/docs/migrate.md).
