Xcode .xcstrings Localization

Lingo.dev seamlessly integrates with Xcode's localization system, making it a breeze to manage translations for your iOS, macOS, watchOS, and 🥽 visionOS apps.

This guide will show you how to set up and use Lingo.dev with Xcode's .xcstrings format.

Setting Up

First, you'll need to set up your i18n.json config file. Here's how it should look for Xcode projects using .xcstrings:

i18n.json

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

TIP

Note that unlike other formats, we don't use the [locale] pattern in the path. That's because Xcode stores all localizations in a single .xcstrings file.

How It Works

The Localizable.xcstrings file is a JSON-based format that Xcode uses to manage localizations. It contains all your strings for all languages in one place. Lingo.dev is smart enough to parse this format and update it correctly.

When you run Lingo.dev, it will:

1. Read your Localizable.xcstrings file;
2. Identify new or changed strings;
3. Translate them to your target languages;
4. Update the Localizable.xcstrings file with the new translations.

Localizing

To localize, simply run:

npx lingo.dev@latest i18n

Lingo.dev will handle the rest, updating your Localizable.xcstrings file with new translations.

Available Languages

To see what languages Lingo.dev supports:

npx lingo.dev@latest show locale sources  # List available source languages
npx lingo.dev@latest show locale targets  # List available target languages

Use these to choose the right locale codes for your Xcode project.

Why This Approach?

Lingo.dev's method for Xcode localization is effective because:

1. It works directly with Xcode's native .xcstrings format, ensuring compatibility with your existing workflow;
2. It updates all languages in one go, keeping your localization file consistent;
3. It uses AI to understand context, providing more accurate translations than traditional methods;
4. It's incremental, only translating what's new or changed, saving time and processing power.

Pro Tips

1. Pluralization: Xcode uses a specific set of features for pluralization. Lingo.dev understands and correctly translates those.

2. Storyboard and XIB files: While Lingo.dev works directly with .xcstrings files, remember that Xcode can extract strings from your Storyboard and XIB files into the Localizable.xcstrings file. This means you can manage all your UI string translations in one place.

3. Multiple .xcstrings files: If your project uses multiple .xcstrings files, you can include them all in your i18n.json config:

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

4. Exclusions: If you have certain .xcstrings files you want to exclude from translation, you can use the exclude option:

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

5. Preserving order: Lingo.dev preserves the order of keys in your .xcstrings files, ensuring that your localization files remain consistent and easy to manage.

6. Automatic cleanup: Lingo.dev automatically removes unused keys from your target localizations when they are deleted from the source file, helping keep your localization files clean and up-to-date.

By leveraging these features, you can maintain a robust, scalable localization setup for your Xcode projects, seamlessly integrating with your existing development workflow.

Other Xcode Localization Formats

While .xcstrings is the recommended format for Xcode localization, Lingo.dev also supports other Xcode-specific formats:

• .strings files: Use the xcode-strings bucket type for traditional .strings files.
• .stringsdict files: Use the xcode-stringsdict bucket type for .stringsdict files, which are used for more complex pluralization rules.

For more information on these formats, check out their respective documentation pages.