Tutorial

Localization

What a catalog is, how a sync translates it, and where to go next.

Checked 2026-10-07

A Catalog 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 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

Catalog

orgs/{org}/projects/{project}/envs/{env}/catalogs/{catalog}

Catalog id

cat_<cell><ulid>

Entry

…/catalogs/{catalog}/entries/{entry}

Glossary

orgs/{org}/projects/{project}/envs/{env}/glossaries/{glossary}

#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 covers the two kinds of key.