xcstrings-localizer

XCStrings Localizer

Translate Xcode String Catalog (.xcstrings) files directly in Claude Code.

When to Activate

Use this skill when the user says things like:

• "localize my app"
• "translate my strings"
• "add Spanish translations"
• "translate Localizable.xcstrings"
• "find untranslated strings"
• "add German to the Widget strings"
• "translate strings in the Login folder"
• "translate error messages only"

Workflow

1. Determine Scope

Ask the user to clarify scope if not specified:

Scope Type	Example Request	How to Filter
All files	"localize my app"	Find all **/*.xcstrings
Single file	"translate Localizable.xcstrings"	Use that specific file
By folder	"translate strings in Source/Login/"	Glob Source/Login/**/*.xcstrings
By target	"translate Widget strings"	Check Xcode project for target membership
By pattern	"translate error messages"	Filter string keys matching pattern
By language	"add Spanish only"	Only add missing Spanish translations

2. Find .xcstrings Files

# Find all xcstrings files in project
find . -name "*.xcstrings" -type f

Or use Glob: **/*.xcstrings

3. Read Target Languages

Check the Xcode project for configured languages:

grep -A 30 "knownRegions" *.xcodeproj/project.pbxproj | grep -E '^\s+"[a-z]{2}(-[A-Z]{2})?"'

Common language codes:

• en - English (usually source)
• es - Spanish
• fr - French
• de - German
• ja - Japanese
• zh-Hans - Chinese Simplified
• zh-Hant - Chinese Traditional
• ko - Korean
• pt-BR - Portuguese (Brazil)
• it - Italian

4. Understand XCStrings JSON Structure

An .xcstrings file is JSON with this structure:

{
  "sourceLanguage": "en",
  "version": "1.0",
  "strings": {
    "string_key": {
      "extractionState": "manual",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "English text"
          }
        },
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "Texto en español"
          }
        }
      }
    }
  }
}

Key fields:

• sourceLanguage: The base language (usually "en")
• strings: Object keyed by string key
• localizations: Object keyed by language code
• stringUnit.state: Translation state
• stringUnit.value: The translated text

Translation states:

• translated - Has a valid translation
• new - Newly added, needs translation
• needs_review - Source changed, translation may be stale
• stale - Marked as outdated

Special metadata:

• shouldTranslate: false - Skip this string (e.g., brand names)
• comment - Context for translators

5. Identify Strings Needing Translation

A string needs translation if:

1. The target language is missing from localizations
2. The state is new or needs_review
3. shouldTranslate is NOT false

6. Preserve Format Specifiers

CRITICAL: Format specifiers must be preserved exactly in translations.

Specifier	Meaning	Example
%@	Object/String	"Hello %@" → "Hola %@"
%d, %i	Integer	"%d items" → "%d elementos"
%ld, %lld	Long integer	Same as %d
%f	Float	"%.2f miles" → "%.2f millas"
%1$@, %2$@	Positional args	"%1$@ sent %2$@" → "%2$@ enviado por %1$@"
%#@count@	Plural reference	Keep exactly as-is
%%	Literal %	Keep as %%

Positional arguments: Languages may reorder arguments. Use positional form (%1$@) to allow reordering.

7. Handle Pluralization

Plural strings have a special structure:

{
  "item_count": {
    "localizations": {
      "en": {
        "variations": {
          "plural": {
            "one": {
              "stringUnit": {
                "state": "translated",
                "value": "%d item"
              }
            },
            "other": {
              "stringUnit": {
                "state": "translated",
                "value": "%d items"
              }
            }
          }
        }
      }
    }
  }
}

Plural categories by language:

• English: one, other
• French: one, many, other
• Russian: one, few, many, other
• Arabic: zero, one, two, few, many, other

8. Translation Process

1. Report findings first:

   Found 3 .xcstrings files:
   - Localizable.xcstrings (245 strings, missing: es 12, fr 245)
   - InfoPlist.xcstrings (5 strings, fully translated)
   - Widget.xcstrings (18 strings, missing: es 3, fr 18)
   
   Target languages from project: en, es, fr
   
   Which would you like to translate?
   

2. Confirm target language(s) if not specified

3. Translate in batches (suggest 10-20 strings at a time for large files)

4. Show translations for review before writing:

   "welcome_message":
     en: "Welcome back, %@!"
     es: "¡Bienvenido de nuevo, %@!"
   
   "item_count" (plural):
     en.one: "%d item"
     en.other: "%d items"
     es.one: "%d elemento"
     es.other: "%d elementos"
   

5. Write back with state set to translated

9. Writing Back

When updating the file:

• Preserve the original JSON structure and ordering
• Set state: "translated" for new translations
• Keep existing translations unless explicitly updating
• Maintain proper JSON formatting (2-space indent)

Tips for Quality Translations

1. Read the app context: Look at surrounding code to understand usage
2. Check for comments: The comment field provides translator context
3. Maintain consistency: Use same terminology across strings
4. Respect placeholders: Never translate %@, %d, etc.
5. Handle HTML/Markdown: If strings contain markup, preserve it
6. Consider length: Some languages expand significantly (German ~30% longer)

Example Session

User: "Add Spanish translations to my app"

1. Find .xcstrings files: Localizable.xcstrings
2. Check knownRegions: en, es, fr
3. Read file, find 15 strings missing Spanish
4. Show: "Found 15 strings needing Spanish translation. Shall I translate them?"
5. Translate with format specifiers preserved
6. Show translations for review
7. Write back on approval