docs menu

Languages and translations

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. 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:

CheckWhen
missing-translationA localized field is empty in a language, or a document has no translation in a language
outdated-translationThe 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.

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 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 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.