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.

IDxcstrings

SourceBuilt-in

Extensions.xcstrings

MIME Typesapplication/json

CapabilitiesRead + Write

How kapi reads it

Parameters

Parameter	Type	Default	Description
extractNonTranslatableContent	boolean	true	Surface an entry's developer comment via a non-translatable fallback block when the entry has no translatable leaf (no localizations, an empty localizations object, or a stale entry skipped because extractStale is off). When off, the part stream is byte-identical to the prior behavior.
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 it live

Configuration

Loading form…

Configuration output

vs defaultsno changes

apiVersion: neokapi/v1
kind: XcstringsFormatConfig
metadata:
  name: xcstrings
spec:
  # (default configuration)

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 %arg token 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