Sanniv Khare 8 min read

From .strings to String Catalogs: a converter on 3 real apps

From .strings to String Catalogs: a converter on 3 real apps

Short answer: you can move a localized table from .strings and .stringsdict to a String Catalog (.xcstrings) with a converter of under 200 lines of Python, keep every translator comment, and mark copied-but-untranslated strings for review instead of calling them done. We ran ours on three open-source iOS apps on GitHub (wikipedia-ios at commit 0aea1dc, home-assistant/iOS at ac2896d, mastodon-ios at 2c165fc, all from November 2026): 203,493 strings across 117, 34 and 51 languages went in, and every one of them came back out of the catalog with the same value. Xcode 26.2’s own catalog compiler accepted the Home Assistant and Mastodon catalogs and rejected Wikipedia’s, for a reason worth checking in your app before you migrate: plural strings in which no form mentions the number.

Why we did this: our Beacon-type banking apps ship Hindi and English, the translators work from spreadsheets, and every new localization feature in Xcode (plural and device variations, review states, the String Catalog editor) only works on .xcstrings. Xcode’s own migration is one click, but we wanted control over comments and states, and a script we can rerun when translations arrive in the old format.

Before and after: a .strings entry with its comment, and the same entry in the String Catalog with comment, extraction state and a Hindi translation

Wikipedia’s string and its comment, before and after the converter.

What a String Catalog stores

A .xcstrings file is JSON. We built this table from Apple’s String Catalog documentation and from a catalog Xcode itself produced: Mastodon already migrated its main Localizable.strings with Xcode, so MastodonSDK/Sources/MastodonLocalization/Resources/Localizable.xcstrings shows exactly what Xcode writes.

Field What it holds What Xcode wrote in Mastodon’s catalog
sourceLanguage the development language en
version file format version 1.1
strings one entry per key 827 keys
extractionState where the key came from migrated (678), manual (149)
comment the note for translators from the old /* */ comment
localizations.<lang>.stringUnit state and value translated (28,046), new (11,682)
variations.plural one stringUnit per plural category used for single-number plurals
substitutions named plural pieces inside a longer sentence, with argNum and formatSpecifier; the number is written as %arg 51 entries

Two details are worth copying from Xcode’s own output. A plural that is the whole string (%#@count@) becomes a plain variations.plural block. A plural inside a sentence (%2$#@v2@ a year) becomes a substitutions entry, and inside it the number is spelled %arg, not %2$d.

The converter

The script reads one table (for example Localizable) from every *.lproj folder, merges the .strings and .stringsdict files, and writes one catalog. The parts that matter:

# 1. .strings: keep the comment above each pair, decode \" \n \U escapes,
#    and read UTF-16 files too (Wikipedia's are UTF-16 with a BOM)
def parse_strings(path): ...

# 2. a value that equals the source text in a non-source language
#    is a copy, not a translation
state = 'needs_review' if (lang != src and val == src_val) else 'translated'

# 3. .stringsdict: whole-string plural -> variations,
#    plural inside a sentence -> substitutions with %arg
if SPEC_RE.fullmatch(fmt):
    return {'variations': {'plural': plural(spec)}}
loc['substitutions'][name] = {'argNum': arg, 'formatSpecifier': fs,
                              'variations': {'plural': pl}}

Each entry is written with extractionState: migrated, the same value Xcode uses for migrated strings, so Xcode does not treat the keys as stale when it cannot find them in code. We marked untranslated copies needs_review where Xcode’s migrator writes new: in a catalog that came from a translation vendor, a copied English string usually means “the vendor did not translate this”, and needs_review keeps it in the translators’ queue without hiding the fact that a value exists.

Five pytest cases cover comments and escapes, the review state, a whole-string plural, a plural inside a sentence and the numberless-plural warning described below; all five pass on Python 3.

Three apps, zero lost strings

We picked open-source apps that still ship .strings tables, ran the converter, then checked the result the other way round: for every key in every original file, the catalog must hold the same value in the same language, or a plural block for it.

Terminal card: the converter's round-trip results on wikipedia-ios, home-assistant/iOS and mastodon-ios

Round-trip check: every original string is in the catalog with the same value.

App and table Languages Input Output catalog Result
wikipedia-ios, WMFNativeLocalizations/Localizable 117 229 files (UTF-16 .strings + .stringsdict) 1,937 keys, 17.7 MB 86,211 strings matched, 4,399 plural entries converted, 1,930 comments kept
home-assistant/iOS, Sources/App/Resources/Localizable 34 34 .strings files 3,412 keys, 19.9 MB 116,008 strings matched; 51,831 copies of English marked needs_review
mastodon-ios, MastodonIntent/Intents 51 80 files 28 keys, 0.3 MB 1,274 strings and 60 plural entries matched

What each app taught us:

  • Wikipedia keeps its .strings in UTF-16. A converter that assumes UTF-8 reads nothing useful; check the byte order mark first. It is also the only one of the three with real comments, and all 1,930 came across.
  • Home Assistant fills every language with the English text where no translation exists, so 51,831 of its 116,008 values are copies of English. A converter that marks everything translated would tell Xcode the app is fully localized in 34 languages. With needs_review, Xcode’s catalog editor shows the real progress per language.
  • Mastodon uses Base.lproj for its Siri Intents table next to en.lproj. We used en as the source language and carried Base over as its own localization, which you may want to drop.

What Xcode’s catalog compiler said

A catalog that loads as JSON is not yet a catalog Xcode will build. When a target contains a .xcstrings file, Xcode compiles it into per-language .strings and .stringsdict files with xcstringstool. We ran that step on all three catalogs on our M1 lab Mac with Xcode 26.2 (xcrun xcstringstool compile <catalog> -o <dir>).

Terminal card: xcstringstool compiles the Home Assistant and Mastodon catalogs and rejects the Wikipedia catalog with a plural error

Home Assistant and Mastodon compiled; Wikipedia stopped at its first plural error.

The Home Assistant catalog (19.9 MB) compiled in about 4 seconds into 34 language folders, Mastodon’s in under a second. Wikipedia’s failed with “Plural variation requires referencing the number in the string”, first for Breton and, in the second run, for Welsh, both on notifications-push-talk-title-format. In the old .stringsdict, that key is a plural whose forms are just “New message” and “New messages”: the number never appears. Foundation has accepted that for years. The catalog compiler does not.

The tool stops at the first error, so we added a check to the converter. It now prints a warning for every plural block in which no form contains a format specifier, and the Wikipedia table has two kinds:

Kind Wikipedia language entries Example
Whole-string plural, no number in any form 118 in 13 keys (1 in English) “New message” / “New messages”
Plural used only for a word ending, number printed outside it 535 in 47 keys French “Ajouter %1$d article%1$#@v1@”, with the plural forms “” and “s”

Home Assistant and Mastodon have none of either kind, which matches what the compiler did with them.

The first kind is what the compiler rejected. For those, Xcode’s error message gives the fix: use two keys, one for a single item and one for several, and choose between them in code. The second kind is a legitimate translator trick, and may not survive the compiler either; rewriting it so each plural form carries the number (%arg article / %arg articles) keeps the grammar and gives the compiler what it wants. Because xcstringstool stops at the first error, we cannot tell from that compile whether it also rejects the second kind; fixing both before migrating is the safe order. In both cases the change belongs with the translators, not in a script that guesses.

Things a converter cannot decide for you

  • Which table to migrate first. One catalog per table; start with the smallest one (an Intents or InfoPlist table) and let it go through a full build and a TestFlight round before moving Localizable.
  • Keys that are English sentences. Old projects often use the English text as the key. That still works in a catalog, but the catalog cannot tell a key from a value then; keep extractionState: migrated so Xcode does not rewrite them from code.
  • The size of the diff. A 17 to 20 MB JSON file is a big pull request. Land the catalog and the removal of the old files in the same commit so the reviewer sees a move, not an addition.

What to check on your own app

  1. Run the converter on one table, read its warnings, and fix every plural that never mentions the number.
  2. Compile the catalog once with xcrun xcstringstool compile <catalog> -o /tmp/out before you add it to the target; it fails fast and names the language and key.
  3. Open the catalog in Xcode and check the per-language percentages: copied English shows up as “Needs Review”, not as done.
  4. Build and look at one plural string per language on a device or Simulator.
  5. Remove the old .strings and .stringsdict for that table in the same commit.

Sources

Made by the team behind this post

Apps from our studio

  • Goes with this post

    Cardigami

    Pop-up greeting cards that rise out of the fold on iPhone Duo.

    iPhone · App Store

    Get
  • Nix

    The Mac uninstaller that finds what the Trash leaves behind: caches, logs, derived data and saved states.

    macOS

    Get
  • BMDB.fun

    Your Bollywood world at a glance, with links straight to the OTT app that streams each film.

    Android TV · Web · Mobile

    Get
  • OneClick QuitAll

    Quit every running app in one click. See memory and CPU first.

    macOS · Mac App Store

    Get

Need this built? Let’s talk.

We build and run apps for Mac, TV, mobile and the web, and write about what we learn.