Apple String Catalogs

Update target-language values inside an XCStrings catalog while preserving its source language and other locales.

An .xcstrings catalog keeps the source and its translations together. The xcode-xcstrings file handler fills target-language entries inside that catalog, retaining other locales in the same file. Expect a changed catalog at the source path rather than a new file per language.

Source values and variations #

An entry with an explicit English source value looks like this:

json
{
  "sourceLanguage": "en",
  "strings": {
    "checkout.title": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Complete your order"
          }
        }
      }
    }
  },
  "version": "1.0"
}

The source-language stringUnit.value supplies text. Supported plural or device variations supply separate leaf values with variation-specific identity. When an entry lacks a source localization, its key becomes the source text. That fallback is useful for source-text keys, but a technical key such as checkout.title is not a substitute for the intended English message.

An entry with shouldTranslate: false is skipped. Catalog comments can remain in the shared structure, but the handler's hints identify the format and variation; it does not establish that each comment becomes translator guidance.

Completeness is per locale #

Completeness is checked inside the requested locale. The handler selects supported source slots that changed or lack a target value. This lets a new language receive translations even though the shared catalog already exists.

Existing translations embedded in the catalog can be reused even with CLI --force. Clearing a separate target input does not remove values inside the source catalog. Use the correction procedure below when an unchanged message needs different wording.

Assembly starts from the current source catalog, carries forward existing locale data for its entries where applicable, and writes the requested translations into its current entries and variations. Review the whole shared-file diff, including source changes and untouched locales. New target units use a translated state; human acceptance remains a separate review decision.

Plural and device variation structure follows supported source leaves. Do not infer that every target language's grammatical forms were generated or verified. Inspect the variation set and render representative cases in the app.

Configure shared-file output #

The CLI infers xcode-xcstrings from .xcstrings and writes output to the source path. Its configuration rejects a separate targetPath for this kind. Follow the CLI file quickstart through retrieval, or use GitHub for managed repository translation.

Correct an existing translation #

For an exact wording correction, edit that locale's value in Xcode and verify it in the app. For regeneration after changing the engine's guidance, first finish pending translation work and preserve the whole catalog. Keep the CLI's existing baseline and include the intended language in targetLocales.

Remove only the target entry you want regenerated. For the example above and a German target, that is strings["checkout.title"].localizations.de; retain en, other locales, and neighboring entries. Save the file, then run an ordinary incremental push:

sh
lingo push --wait

The changed catalog is submitted with that target missing, so the selected entry needs translation. Do not edit the file during the wait. Inspect the new German value and the whole catalog diff before accepting it. For an entry with plural or device variations, removing its locale entry regenerates all its supported source variations.

Use this procedure with the saved baseline and a plain push. Positional patterns, --backfill-missing, and --key select different work; purge skips the shared file.

Review the whole catalog change #

Preserve the committed catalog or a local copy before replacing or cleaning it up. CLI purge skips this format because its source and output share a path. Remove the intended locale entry as described above when regenerating one translation.

CLI catalog checks do not establish XCStrings locale completeness. Use Xcode and application checks for resource membership, development language, multiple catalogs, placeholders, and displayed variations. See Localize an iOS app for that workflow. Legacy strings and stringsdict retain separate per-locale file semantics.