Localizable.xcstrings
Translation File Format

Localizable.xcstrings file format

Localizable.xcstrings is a JSON-like format introduced by Apple at WWDC 2022 for localization purposes in Xcode. It includes translations for all messages used in macOS, iOS, and other Apple platform applications. Unlike the traditional Localizable.strings format, xcstrings is more structured and includes comprehensive information about translation state, comments, source language, variations, pluralization, and device-specific translations all in a single file.

{
  "version": "1.0",
  "sourceLanguage": "en",
  "strings": {
    "hello_world": {
      "shouldTranslate": true,
      "comment": "Main greeting message for users",
      "extractionState": "manual",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Hello World"
          }
        },
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "Hola Mundo"
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated", 
            "value": "Bonjour le monde"
          }
        }
      }
    }
  }
}

Every xcstrings file contains all translations for all supported languages in a single file. This is a major improvement over the traditional approach where each language required its own separate .strings file in different lproj directories. The format includes metadata like translation states, extraction information, and developer comments that help coordinate translation workflows.

Key advantages over Localizable.strings

The xcstrings format provides several improvements over the traditional .strings format:

• Single file approach: All languages are stored in one file instead of separate files per language
• Enhanced metadata: Includes translation states, extraction information, and structured comments
• Better tooling support: Xcode provides superior editing, validation, and collaboration features
• Built-in pluralization: Native support for plural forms without requiring separate .stringsdict files
• Device variants: Support for device-specific translations (iPhone, iPad, Mac, etc.)
• Substitutions: Advanced placeholder and formatting capabilities
• Version control friendly: JSON structure makes it easier to track changes and resolve conflicts

Device variants and platform-specific translations

One of the most powerful features of xcstrings is support for device-specific translations. You can provide different translations for different Apple devices, allowing for optimized user experiences across platforms.

{
  "version": "1.0",
  "sourceLanguage": "en",
  "strings": {
    "search_action": {
      "comment": "Search action that varies by device",
      "extractionState": "manual",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Find"
          }
        },
        "de": {
          "variations": {
            "device": {
              "mac": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Suchen"
                }
              },
              "iphone": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Finde"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Suche"
                }
              }
            }
          }
        }
      }
    }
  }
}

Available device variants include: mac, iphone, ipad, watch, tv, and other for fallback cases.

Pluralization support

Unlike traditional .strings files, xcstrings includes native pluralization support without requiring separate .stringsdict files.This makes managing plural forms much more straightforward and keeps all localization data in one place.

{
  "version": "1.0",
  "sourceLanguage": "en",
  "strings": {
    "item_count": {
      "comment": "Number of items in cart",
      "localizations": {
        "en": {
          "variations": {
            "plural": {
              "zero": {
                "stringUnit": {
                  "state": "translated",
                  "value": "No items"
                }
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld item"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld items"
                }
              }
            }
          }
        },
        "pl": {
          "variations": {
            "plural": {
              "zero": {
                "stringUnit": {
                  "state": "translated",
                  "value": "Brak przedmiotów"
                }
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld przedmiot"
                }
              },
              "few": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld przedmioty"
                }
              },
              "many": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld przedmiotów"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld przedmiotów"
                }
              }
            }
          }
        }
      }
    }
  }
}

Supported plural forms include: zero, one, two, few, many, and other. Different languages use different combinations of these forms based on their grammatical rules.

Translation states and workflow management

The xcstrings format includes sophisticated state management for tracking translation progress. Each translation can have different states that help coordinate translation workflows and identify what needs attention.

• translated: The translation is complete and ready for use
• needs_review: The translation exists but requires review
• new: A new translation that hasn't been completed yet
• stale: The source text has changed and the translation needs updating

The extractionState field tracks how the translation was discovered: extracted_with_value for automatically extracted strings, manual for manually added translations, or migrated for translations converted from other formats.

How to use Localizable.xcstrings in Xcode?

Setting up xcstrings in your iOS or macOS project is straightforward and provides immediate benefits over the traditional .strings approach. Xcode provides excellent tooling support for managing xcstrings files.

Migration from Localizable.strings

Apple provides tools to help migrate from the traditional .strings format to the modern .xcstrings format.The migration process preserves your existing translations while adding the enhanced capabilities of the new format.

Automatic migration in Xcode

Xcode can automatically convert your existing Localizable.strings files to the xcstrings format:

1. Select your existing .strings files in the Project Navigator
2. Right-click and choose "Migrate to String Catalog"
3. Xcode will create a new .xcstrings file and import all translations
4. Review the migrated content and delete the old .strings files

What gets migrated

• Translation keys and values: All existing key-value pairs are preserved
• Comments: Developer comments from NSLocalizedString calls are maintained
• Plural forms: .stringsdict plural definitions are converted to xcstrings format
• Language support: All existing language localizations are included

SimpleLocalize and ICU message format conversion

SimpleLocalize automatically converts xcstrings device variants and pluralization to standard ICU message format.This allows you to export your translations to other file formats while maintaining the advanced features of xcstrings.

# Device variant conversion
Original xcstrings: mac="Click here", iphone="Tap here", other="Press here"
ICU format: {DEVICE, select, mac {Click here} iphone {Tap here} other {Press here}}

# Pluralization conversion  
Original xcstrings: zero="No items", one="%lld item", other="%lld items"
ICU format: {COUNT, plural, zero {No items} one {%lld item} other {%lld items}}

This conversion enables you to use xcstrings as your primary format while still being able to export to other platforms and frameworks that use different localization systems.

Where Localizable.xcstrings is used?

Localizable.xcstrings files are used across all Apple platforms and development environments. The format is supported by Xcode 14+ and works with all Apple operating systems and frameworks.

iOS

macOS

Swift

SwiftUI

Xcode

watchOS

tvOS

visionOS

Multi-file support with namespaces

If you split translations into multiple files in your application, you can use namespaces in SimpleLocalize to manage them separately. This allows you to organize translations by feature, module, or any other logical grouping while still taking advantage of the xcstrings format benefits.

Project structure:
Localizable-Auth.xcstrings      # Authentication features
Localizable-Settings.xcstrings  # Settings and preferences  
Localizable-Messages.xcstrings  # Chat and messaging
Localizable-Main.xcstrings      # Core app features

SimpleLocalize CLI commands:
simplelocalize upload --uploadFormat localizable-xcstrings --uploadPath ./Localizable-{ns}.xcstrings
simplelocalize download --downloadFormat localizable-xcstrings --downloadPath ./Localizable-{ns}.xcstrings

Best practices for xcstrings files

To get the most out of the xcstrings format, follow these best practices:

• Use descriptive comments: Take advantage of the comment field to provide context for translators
• Leverage extraction states: Use automatic extraction for most strings, but manually add strings that need special handling
• Organize with namespaces: Split large projects into multiple xcstrings files using meaningful names
• Take advantage of device variants: Provide platform-specific translations where appropriate
• Use proper plural forms: Implement correct pluralization for all supported languages
• Manage translation states: Keep track of translation progress using the built-in state system
• Regular validation: Use Xcode's validation tools to check for missing translations and errors

How to keep xcstrings files synchronized?

Managing xcstrings files across multiple languages and team members requires proper workflow coordination.While the single-file approach simplifies some aspects, you still need tools to handle collaboration, updates, and quality assurance. SimpleLocalize provides comprehensive support for xcstrings files with features designed for modern localization workflows.

With SimpleLocalize, you can upload your xcstrings files, collaborate with translators using our web-based editor, leverage auto-translation for new content, and download updated files with all the advanced xcstrings features intact. Our platform preserves device variants, pluralization, and metadata while providing additional workflow features like comments, reviews, and automation.