Apple String Catalog format (.xcstrings)

The Apple String Catalog format reads .xcstrings files, the default string-resource 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-locale 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 the source language has no entry of its own) 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	Vis en oppføringens utviklerkommentar via en ikke-oversettbar reserveblokk når oppføringen ikke har noen oversettbar løvnode (ingen lokaliseringer, et tomt lokaliseringsobjekt, eller en foreldet oppføring som hoppes over fordi extractStale er av). Når dette er av, er delstrømmen byte-identisk med den tidligere oppførselen.
extractStale	boolean	true	Emit oppføringer hvis extractionState er "stale" (kildeteksten vises ikke lenger i kodebasen) som oversettbare blokker.
markTranslatedState	string	translated	Tilstandsverdien for stringUnit som skrives for en lokalisering som fylles ut for første gang. Eksisterende tilstander bevares uendret ved tur-retur.

Configure it live

Configuration

Loading form…

Configuration output

vs defaults no 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 locales instead of translated.

markTranslatedState: needs_review

Processing notes

• A catalog is multilingual, so one file carries the source language and all targets, and 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