Apple String Catalog format (.xcstrings)
The Apple String Catalog format reads .xcstrings files — the default
localization container for iOS, macOS, and other Apple-platform projects
since Xcode 15. Unlike legacy .strings/.stringsdict, a single catalog
holds the source language and every translation in one JSON document,
carrying per-localization state (new, translated, needs_review),
developer comments, and plural / device / substitution variations.
Each translatable leaf value becomes a block. The source string (or the
entry key, when no source-language localization is present) is the source;
per-locale stringUnit values are the targets. Developer comments surface
as translator notes, and printf specifiers (%@, %lld, %1$@, and
Apple's %arg substitution token) are protected as inline placeholders so
they are never altered. Writing back is byte-faithful: only changed values
and states are rewritten, leaving the rest of the catalog untouched.
How kapi reads it
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
extractStale | boolean | true | Emit entries whose extractionState is "stale" (the source string no longer appears in the code base) as translatable blocks. |
markTranslatedState | string | translated | The stringUnit state value written for a localization populated for the first time. Existing states are preserved verbatim on round-trip. |
Configure these parameters interactively and copy the YAML on the Format Reference.
Examples
Skip stale entries
Do not emit entries Xcode has flagged as stale.
extractStale: false
Mark new translations for review
Write a needs_review state for newly populated localizations instead of translated.
markTranslatedState: needs_review
Processing notes
A catalog is multilingual — one file carries the source language and all targets, so reading yields blocks with a source plus multiple target locales.
Plural (CLDR categories), device (iphone/ipad/mac/…), and substitution variations each expand into their own leaf blocks, keyed by the variation path.
printf specifiers and Apple's substitution
%argtoken are extracted as inline placeholders and must not be translated.Output is byte-faithful: an unchanged catalog round-trips exactly; only modified values and states are rewritten.
← Back to the Format Reference