---
title: Localization
description: Translate your app's strings in CI with AI, a translation memory and a glossary - send your source files, get every locale back checked.
type: tutorial
product: localization
summary: What a catalog is, how a sync translates it, and where to go next.
updated: 2026-10-07
order: 0
---

A [Catalog](/docs/api/catalogs) is your app's string catalog: one source
locale, the locales to translate into, and how to translate them. Your build
sends the source files to `:sync`; Sylphx Localization translates what is new
or changed and checks every translation; `:export` returns one file per locale
for you to commit. There is nothing to deploy and no translation vendor to
sign up with: one key in your project is enough.

## What a catalog gives you

- **Only the delta is translated.** Each message is keyed by its source text
  and a hash of it, so a sync translates new and changed messages and reuses
  the rest. Translations already in the translation memory are free.
- **Checked before it ships.** Every translation is checked for syntax,
  placeholders, markup, plural forms, length and glossary terms, and repaired
  once when it fails. A translation that still fails is never exported.
- **Your edits win.** Commit a changed translation and the next sync records it
  as a pinned human override, so it is never translated over.
- **Real plurals.** Messages are Unicode MessageFormat 2; ICU MessageFormat 1
  files (ICU JSON, gettext `.po`) and XLIFF 2.0 are read and written through
  the same catalog.
- **A voice and a glossary.** `spec.tone` and `spec.locale_guidance` steer the
  wording; a [Glossary](/docs/api/glossaries) fixes how a term is translated,
  keeps it untranslated, or forbids it.
- **Pseudo-locales.** `en-XA` (longer, accented), `ar-XB` (right to left) and
  `zh-XW` (full width) are generated at export to test layouts, never stored.
- **Bounded calls.** A sync works within a fixed time; call it again until
  `pending` is 0. It is idempotent, so a CI retry is safe.

## Names and ids

<KeyValue
	items={[
		{ key: 'Catalog', value: 'orgs/{org}/projects/{project}/envs/{env}/catalogs/{catalog}', mono: true },
		{ key: 'Catalog id', value: 'cat_<cell><ulid>', mono: true },
		{ key: 'Entry', value: '…/catalogs/{catalog}/entries/{entry}', mono: true },
		{ key: 'Glossary', value: 'orgs/{org}/projects/{project}/envs/{env}/glossaries/{glossary}', mono: true },
	]}
/>

## The scopes

- `localization:write` — creating and changing catalogs and glossaries,
  `:sync`, and pinning a translation.
- `localization:read` — reading catalogs, entries and glossaries, and
  `:export`.

Translation is billed by the source characters translated per target locale
(`usage.translated_characters` on each sync); memory matches are free.
[Keys and scopes](/docs/platform/keys-and-scopes) covers the two kinds of key.

<RelatedDocs
	links={[
		{
			href: '/docs/localization/quickstart',
			label: 'Quickstart',
			description: 'Create a catalog, sync a source file, and export the translations.',
		},
		{
			href: '/docs/api/catalogs',
			label: 'The catalogs collection',
			description: 'Every method, field and example.',
		},
		{
			href: '/docs/api/entries',
			label: 'The entries collection',
			description: 'Each message, its translations and their QA state.',
		},
		{
			href: '/docs/api/glossaries',
			label: 'The glossaries collection',
			description: 'Terms to translate one way, keep, or forbid.',
		},
	]}
/>