How to translate an Xcode string catalog

A string catalog is one .xcstrings file that holds every user facing string of a target and its translations. Xcode fills in the keys when you build. The translations are your job, and there are three practical ways to get them.

By Apsterio, the makers of Rifinita. Updated on .

How a string catalog works

String catalogs arrived in Xcode 15 and replace the older .strings and .stringsdict files. The file is JSON, but you edit it in Xcode’s catalog editor: keys in one column, a column per language. Each time you build, Xcode finds the strings in your code and adds new keys.

Every string has a state in each language:

  • New: no translation yet.
  • Translated: done.
  • Needs review: a translation exists but someone should check it, for example after the source text changed.
  • Stale: the key is no longer found in the code.

The percentage Xcode shows next to a language is the share of strings in the Translated state.

Plurals and device variations

A string with a number in it can vary by plural. Each language gets the plural forms it needs: English has one and other, Russian has one, few, many and other, Japanese has only other. A string can also vary by device, so “Tap” on iPhone can read “Click” on Mac. A translator has to fill every form, and a missing form shows the source language to the user.

Placeholders

Format specifiers such as %@ and %lld stand for values inserted at run time. A translation has to keep every one of them, with the same type. When a language needs a different word order, number them: %1$@ and %2$lld. A dropped or altered placeholder is the most common way a translation breaks an app, and it does not show until that screen is opened in that language.

Three ways to translate a catalog

Send it to a translator

In Xcode choose Product, then Export Localizations. Xcode writes one .xcloc bundle per language with an XLIFF file inside. A translator fills it in their own tool and you bring it back with Import Localizations. This is the slowest route and the most reliable for marketing text.

Use machine translation

macOS includes Apple’s translator, which runs on the device and costs nothing. DeepL is strong for European languages. Both translate a string without knowing where it appears, so short labels come out wrong more often than sentences: “Save” can become the word for saving money.

Use an AI model with context

A language model can be told what the app is, who uses it, which terms must stay as they are and what the comment on each key says. That context is what fixes short labels. Give it a glossary for product terms and ask it to keep placeholders unchanged, then check that it did.

What to check afterwards

  • Every placeholder in the source is in the translation.
  • Every plural form the language needs is filled.
  • Product and feature names are the same everywhere.
  • The longest translations fit their buttons. German and Russian are the usual test.
  • Strings marked Needs review were read by someone before release.

Comments are worth writing

The comment on a key is the only context a translator or a model gets. “Button that saves the workout” removes the guess about which kind of save is meant. Writing comments for the hundred shortest strings improves a translation more than changing the engine.