iOS & macOS

Last updated: August 20, 2025

Overview

iOS and macOS applications development there are four localization file formats:

We support all these formats, allowing you to manage translations in the way that best fits your project.

The XCStrings format provides better structure with translation states, comments, pluralization, device variants, and substitutions. XCLOC is ideal for working with translation management systems using industry-standard XLIFF format.

Installation

Install SimpleLocalize CLI to automate import & export of translation files.

curl -s https://get.simplelocalize.io/2.10/install | bash
curl -s https://get.simplelocalize.io/2.10/install | bash

Intel and Apple Silicon Macs are both supported.

Upload XCStrings source file

Upload your Localizable.xcstrings file to SimpleLocalize:

$ simplelocalize upload \ --apiKey YOUR_API_KEY \ --uploadFormat localizable-xcstrings \ --uploadPath ./Localizable.xcstrings
$ simplelocalize upload \
        --apiKey YOUR_API_KEY \
        --uploadFormat localizable-xcstrings \
        --uploadPath ./Localizable.xcstrings

For multiple namespace files:

simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat localizable-xcstrings \
  --uploadPath ./Localizable-{ns}.xcstrings

Download XCStrings files

Download translated XCStrings files:

# Single file
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat localizable-xcstrings \
  --downloadPath ./Localizable.xcstrings

# Multiple namespaces
simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat localizable-xcstrings \
  --downloadPath ./Localizable-{ns}.xcstrings

XCStrings Features

The XCStrings format supports advanced localization features:

  • Device variants - Different translations for iPhone, iPad, Mac, Apple Watch, Apple TV
  • Pluralization - Proper plural forms (zero, one, two, few, many, other)
  • Translation states - Track translation progress and review status
  • Comments - Context for translators
  • Substitutions - Dynamic placeholders with formatting

SimpleLocalize automatically converts these to ICU message format for cross-platform compatibility.

Xcode Localization Catalog (.xcloc)

XCLOC is a collection of XLIFF 1.2 files with metadata, designed for translation exchange with translation management systems. It's particularly useful when working with external translators or translation agencies.

Upload XCLOC files

Upload XLIFF files from your XCLOC catalog:

simplelocalize upload --apiKey <PROJECT_KEY> \
  --uploadFormat xliff:1.2 \
  --uploadPath ./MyApp.xcloc/Localizations/{lang}.xliff

Download XCLOC files

Export translations as XCLOC-compatible XLIFF files:

simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat xliff:1.2 \
  --downloadPath ./MyApp.xcloc/Localizations/{lang}.xliff

XCLOC Structure

An XCLOC catalog appears as a single file but is actually a directory:

MyApp.xcloc/
├── Contents.json
└── Localizations/
    ├── en.xliff
    ├── de.xliff
    └── fr.xliff

When to use XCLOC

XCLOC is ideal when:

  • Working with external translation agencies that use XLIFF
  • Preserving translation metadata and states
  • Maintaining compatibility with CAT (Computer-Assisted Translation) tools
  • Need to preserve "Managed: Automatically" state in Xcode

Legacy Localizable.strings Format

Upload Localizable.strings files

For projects still using the legacy format:

$ simplelocalize upload \ --apiKey YOUR_API_KEY \ --uploadFormat localizable-strings \ --uploadPath ./Resources/Localization/en.lproj/Localizable.strings
$ simplelocalize upload \
        --apiKey YOUR_API_KEY \
        --uploadFormat localizable-strings \
        --uploadPath ./Resources/Localization/en.lproj/Localizable.strings

Download Localizable.strings files

simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadPath ./Resources/Localization/{lang}.lproj/Localizable.strings \
  --downloadFormat localizable-strings

Translate messages

Now you can translate your iOS / macOS strings using SimpleLocalize.

If you want to translate your app in multiple languages fast, you use auto-translation.

Migration from .strings to .xcstrings

To migrate from legacy Localizable.strings to modern XCStrings format:

  1. In Xcode, select your Localizable.strings file
  2. Choose Editor → Convert to String Catalog
  3. Upload the new .xcstrings file to SimpleLocalize
  4. Update your download commands to use localizable-xcstrings format

Optionally, you can import your existing Localizable.strings files into SimpleLocalize and then export them as XCStrings format.

Resources