Locales and translation
Three different locale ideas share similar names. Keeping them apart avoids most translation bugs.
1. UI locale
The language of API error strings and docs. It is part of the URL (/api/v1/{locale}/...) or the MCP session. It does not change any stored content.
2. Content locale
Which translation overlay you read or write on a design document. Pass contentLocale on page, component, and chrome reads and writes. Overlays are sparse: only changed leaves are stored.
Localization keys are blockId:leaf:path. Root fields omit the block id prefix. save_localization writes overlays without touching the shared layout, and get_localization reports the gaps for a locale.
3. Localized entry values
Per-locale field values on an object entry, passed as localizedValuesByLocale on save_entry. This is unrelated to page overlays even when both are called "translation".
Enabled locales
Website locales define the primary locale and the enabled set. A page can have a different path per locale, and a new locale gets a copy of the primary locale's head so its route does not 404.
Localized identifiers
When an object type has a localizable identifier, each locale gets its own public segment. Changing a segment, or changing the identifier field, writes a locale-scoped 301.