localize.dev

Docs / Translate / String Catalog

Translate Xcode String Catalogs

Fill in Localizable.xcstrings for SwiftUI and UIKit apps, with %@ and %lld specifiers, plural variations, %#@name@ substitutions and comments as context. Legacy .strings files too.

How it works

A String Catalog holds every language in one file. localize-dev translate adds the missing languages to each entry with state set to translated, keeps the file’s key order and Xcode’s JSON layout so the diff stays small, and sends each string’s comment as context. Strings with shouldTranslate off are skipped.

Plural variations get the forms each language uses. A sentence with several counts (%#@photos@ in %#@albums@) is translated as the sentence plus each count’s forms, and written only once all of them are done. Device variations are left for Xcode’s editor. Legacy en.lproj/Localizable.strings files are translated into <lang>.lproj too, comments kept.

Before and after

Real output of localize-dev translate --locales de on the first file. German is added to each entry, the plural variation included, in Xcode’s own formatting.

Localizable.xcstrings
{
  "sourceLanguage" : "en",
  "strings" : {
    "Delete Photo" : {
      "comment" : "Button in the photo detail toolbar"
    },
    "Hello, %@!" : {

    },
    "%lld photos" : {
      "localizations" : {
        "en" : {
          "variations" : {
            "plural" : {
              "one" : { "stringUnit" : { "state" : "translated", "value" : "%lld photo" } },
              "other" : { "stringUnit" : { "state" : "translated", "value" : "%lld photos" } }
            }
          }
        }
      }
    }
  },
  "version" : "1.0"
}
Localizable.xcstrings · German
{
  "sourceLanguage" : "en",
  "strings" : {
    "Delete Photo" : {
      "comment" : "Button in the photo detail toolbar",
      "localizations" : {
        "de" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "Foto löschen"
          }
        }
      }
    },
    "Hello, %@!" : {
      "localizations" : {
        "de" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "Hallo, %@!"
          }
        }
      }
    },
    "%lld photos" : {
      "localizations" : {
        "de" : {
          "variations" : {
            "plural" : {
              "one" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%lld Foto"
                }
              },
              "other" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%lld Fotos"
                }
              }
            }
          }
        },
        "en" : {
          "variations" : {
            "plural" : {
              "one" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%lld photo"
                }
              },
              "other" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%lld photos"
                }
              }
            }
          }
        }
      }
    }
  },
  "version" : "1.0"
}

What stays intact

  • %@, %lld, %1$@ and other specifiers, checked
  • Plural variations and %#@name@ substitutions
  • Xcode’s key order and JSON layout, so Xcode doesn’t rewrite the file
  • Translator comments, in .strings files as well

Common mistakes, and how they’re avoided

Reordered arguments

German and Japanese often need the arguments of a sentence in another order. Unnumbered %@ arguments mean something by their position, so a translation that reorders them is rejected. Numbered ones like %1$@ can move.

Half-translated substitutions

A string with %#@name@ needs its sentence and every count’s forms in each language. They’re written together or not at all.

English plural forms copied into Japanese

Japanese, Chinese and Korean have one plural form. Only other is written for them, instead of a one copied from English.

Run it

In the folder that holds your locale files. Languages without a file yet get one. --dry-run shows what would change first.

npx localize-dev login

# Preview, then write the missing translations
npx localize-dev translate --dry-run -l es,fr,de
npx localize-dev translate -l es,fr,de

Then keep it complete in CI. This needs no API key and fails when a language is missing translations:

npx localize-dev check --only translations

Free for 1,000 strings a month. A string counts once however many languages it goes into. Create a free account

Guides for apps that use this format

When the copy is still hardcoded in your code, localize-dev run moves it into this format first.