Xcode Localization Catalog

Xcode Localization Catalog (.xcloc) is a collection of localization files in XLIFF 1.2 format and a Contents.json file that describes the catalog. It is used to manage translations in Xcode projects.

The XCLOC format is a successor to the Localizable.strings and Localizable.stringsdict file formats. Unlike the Localizable.strings format, XCLOC is a collection of files that includes much more information about the translation state, comments, source language, variations, pluralization, and substitutions. It's is also something different than the Localizable.xcstrings file format, which is a single JSON-like file format used internally in Xcode projects.

Xcode Localization Catalog vs XC Strings

XCLOC is a collection of localization files in XLIFF 1.2 format, while XC Strings is a single JSON-like file format.

Feature	.xcstrings	.xcloc
Format	JSON	Folder with XLIFF + metadata
Purpose	Project repository	Translation exchange
Source of truth	Yes	No
Xcode support	Translation editor	Import/Export
Managed: Automatically	Lost when manually replaced	Preserved on import

When to use XCLOC and when to use XC Strings?

It depends on your project structure and how you want to manage translations, but in general, XCLOC was introduced to be used with translation management systems like SimpleLocalize, as it uses XLIFF 1.2 format for translations, which is a standard format for localization files. XC Strings is a single file format used internally in Xcode projects. One important difference worth mentioning is that Xcode maintains the "Managed: Automatically" state when XC Strings is used, but this state is lost when files are manually replaced. With XCLOC, this managed state is preserved during import operations.

XCLOC is a catalog of XLIFF files

XCLOC is a catalog that appears in macOS systems as a file with the .xcloc extension, but it is actually a directory that contains a Contents.json file and a collection of localization files in XLIFF 1.2 format.

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

Contents.json structure

The Contents.json file describes the catalog and contains metadata about the localization project. Here's an example of what it looks like:

{
  "developmentRegion" : "en",
  "project" : "MyApp.xcodeproj",
  "targetLocale" : "pl",
  "toolInfo" : {
    "toolBuildNumber" : "15A240d",
    "toolID" : "com.apple.dt.xcode",
    "toolName" : "Xcode",
    "toolVersion" : "15.0"
  },
  "version" : "1.0"
}

The Contents.json file includes:

developmentRegion - The source language/locale of the project (e.g., "en" for English)
project - The name of the Xcode project file
targetLocale - The target language for this localization catalog
toolInfo - Information about the tool that created the catalog, including Xcode version details
version - The version of the XCLOC format specification

The Localizations directory contains localization files for each language in XLIFF 1.2 format.

Since XCLOC is just a collection of XLIFF files, it is natively supported by SimpleLocalize. You can import and export translations in XCLOC format using the SimpleLocalize CLI or the web interface.

Import XCLOC with CLI

Example of importing XCLOC to SimpleLocalize:

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

Learn more about SimpleLocalize CLI and translations upload feature.

Add --overwrite flag to update existing translations in SimpleLocalize from the imported file. Otherwise, only new translations will be added.

Export translations to XCLOC

Example of exporting translations from the translation editor to XCLOC file format using the CLI:

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

Learn more about SimpleLocalize CLI and translations download feature.