Lingo.dev Docs

Appearance

Translate Modern Xcode Apps with .xcstrings Support ​

Streamline localization for your iOS, macOS, watchOS, and visionOS apps with Lingo.dev's native support for Xcode's modern .xcstrings format - the recommended approach for Apple platform localization.

Quick Setup ​

Create an i18n.json configuration file in your project root:

json
{
  "version": 1.2,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "xcode-xcstrings": {
      "include": ["my-app/Localizable.xcstrings"]
    }
  }
}

TIP

Unlike other formats, .xcstrings files don't use the [locale] placeholder in paths because they store all languages in a single file.

One Command Translation ​

Translate all your app strings with a single command:

bash
npx lingo.dev@latest i18n

This automatically:

  1. Reads your .xcstrings file
  2. Identifies new or modified strings
  3. Translates only what's changed
  4. Updates the file with all target languages

How .xcstrings Works ​

The .xcstrings format is Apple's modern approach to localization:

  • Single-file storage: All languages are contained in one JSON-based file
  • Built-in metadata: Includes comments, variations, and formatting information
  • Xcode integration: Directly supported in Xcode's localization workflow

Find Supported Languages ​

Discover all available language options:

bash
# View source language options
npx lingo.dev@latest show locale sources

# View target language options
npx lingo.dev@latest show locale targets

Advanced Features ​

Pluralization Support ​

Lingo.dev correctly handles Xcode's pluralization system:

json
{
  "items-count": {
    "extractionState": "manual",
    "localizations": {
      "en": {
        "variations": {
          "plural": {
            "one": {
              "stringUnit": {
                "state": "translated",
                "text": "%d item"
              }
            },
            "other": {
              "stringUnit": {
                "state": "translated",
                "text": "%d items"
              }
            }
          }
        }
      }
    }
  }
}

All plural variations are properly translated according to each language's grammatical rules.

UI Integration ​

Combine strings from multiple sources:

  • Storyboard/XIB extraction: Xcode can extract UI strings into your .xcstrings file
  • SwiftUI text: Marked strings from SwiftUI views
  • Code strings: Localized strings from your Swift/Objective-C code

This creates a single source of truth for all your app's text.

Configuration Options ​

Multiple Files Support ​

Include all your project's .xcstrings files:

json
"xcode-xcstrings": {
  "include": [
    "my-app/Localizable.xcstrings",
    "my-app/InfoPlist.xcstrings",
    "my-app/CustomModule.xcstrings"
  ]
}

Exclude Specific Files ​

Keep certain files untranslated:

json
"xcode-xcstrings": {
  "include": ["my-app/**/*.xcstrings"],
  "exclude": ["my-app/DoNotTranslate.xcstrings"]
}

Why iOS Developers Choose This Approach ​

  1. Native Integration: Works directly with Xcode's recommended localization format
  2. All-in-One: Updates all languages in a single file
  3. Context-Aware: AI understands app context for better translations
  4. Incremental Updates: Only translates what's changed, saving time and resources
  5. Structure Preservation: Maintains all metadata, comments, and formatting

Additional Benefits ​

  • Key Order Preservation: Maintains the exact order of your string keys
  • Automatic Cleanup: Removes unused keys from target languages when deleted from source
  • Format Specifier Protection: Preserves all format specifiers (%@, %d, etc.)

Other Apple Localization Formats ​

Lingo.dev supports all Xcode localization formats:

For most new projects, .xcstrings is the recommended approach as it combines the benefits of both formats in a single, modern solution.