// Parsers

iOS XCStrings Parser Reference

Technical reference for how String Catalog parses .xcstrings files, tracks state, handles renames, and normalizes write-back output.

The XCStrings parser handles iOS app localization String Catalog JSON with parser-aware behavior beyond simple key/value extraction.

Detection Rules

File extension: .xcstrings

Supported File Patterns

Object-shaped and list-shaped strings
Empty and comment-only entries
Optional version capture

Parsing Behavior

Stores keys and localized variants with stable identity across syncs.

Locale Normalization Behavior

Normalizes locale codes and resolves supported languages with Apple-locale fallback semantics.
Preserves locale variants where needed (for example en-US).

Review State Handling

Coalesces repeated non-base needs_review triggers.
Avoids duplicate processing when replayed inputs are unchanged.
Preserves in-flight review rows (pending / in_progress) during follow-up syncs.

Rename Handling

When enabled, key-rename detection can identify carried-over translations and mark them for review or retranslation.

Write-Back Normalization

XCStrings output preserves key order, source language, and localization structures including plural variations.

Edge Cases Handled

Replayed inputs that should not trigger duplicate processing.
Mixed locale code styles (en, en-US, en_US) that should resolve to one tracked locale.
In-flight review rows that should not be reset by duplicate sync input.