XC String format is a JSON-like format introduced by Apple at WWDC 2022 for localization purposes in Xcode. It includes translations for all messages used in macOS and iOS applications.
XC Strings format is a successor of the Localizable.strings and Localizable.stringsdict file formats. Unlike the Localizable.strings format, the XC Strings is more structured, because it includes much more information about the translation state, comments, source language, variations, pluralization, and substitutions.
File format example
Every XC String file format requires a version field that specifies the version of the format. The sourceLanguage field contains the language code of the source language.
The strings field contains all translations for the given key.
Each translation key has information about if the translation should be translated, a comment for the translator, extraction state, and localizations for each language.
{
"version": "1.0",
"sourceLanguage" : "en",
"strings" : {
"hello_world" : {
"shouldTranslate": true,
"comment" : "Here is a comment for the translator",
"extractionState" : "manual",
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
"value" : "Hello World"
}
},
"pl" : {
"stringUnit" : {
"state" : "translated",
"value" : "Witaj świecie"
}
},
"de" : {
"stringUnit" : {
"state" : "translated",
"value" : "Hallo Welt"
}
}
}
}
}
}
In the example above, the hello_world key has translations for the English, Polish, and German languages.
During file export, SimpleLocalize will use the default language key of your project for the source language. If the default language is not set in your project, the source language will be set to
en.
Device variants
Device variants are used to specify a translation for a specific Apple device,
such as iPhone, Mac, iPad, or Apple Watch.
The device variants are specified in the localizations field as variants.
{
"version": "1.0",
"sourceLanguage" : "en",
"strings" : {
"search_label" : {
"comment" : "Device variant translation example",
"extractionState" : "manual",
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
"value" : "Find"
}
},
"de" : {
"variations" : {
"device" : {
"mac" : {
"stringUnit" : {
"state" : "translated",
"value" : "Suche"
}
},
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "Finde"
}
}
}
}
}
}
}
}
}
In the example above, the German ('de') language has two translations for the search_label key.
The first translation ('Suche') is for computers ('mac'), and the second translation ('Finde') is for all other devices ('other').
The English language has only one translation for the key for all devices.
List of available device variants:
maciphoneipadwatchtv
SimpleLocalize converts XC Strings device variants to standard ICU message format, so they can be exported to other file formats, and maintain the device variant information, for example:
# English translation
Find
# German translation
{DEVICE, select, mac {Suche} other {Finde}}
DEVICEis a variable that represents the device variant andselectis an ICU message format keyword. Themacandotherare the device variant values.
Pluralized translations
{
"version": "1.0",
"sourceLanguage" : "en",
"strings" : {
"things_label" : {
"comment" : "Pluralized translation",
"localizations" : {
"en" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld thing"
}
},
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld things"
}
}
}
}
},
"de" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld Ding"
}
},
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld Dinge"
}
}
}
}
}
}
}
}
}
In the example above, the things_label key has pluralized translations for the English and German languages.
Same as with device variants, SimpleLocalize converts pluralized translations to ICU message format.
# English translation
{COUNT, plural, one {%lld thing} other {%lld things}}
# German translation
{COUNT, plural, one {%lld Ding} other {%lld Dinge}}
COUNTis a variable that represents the count of things,pluralis an ICU message format keyword, andoneandotherare the pluralization values.
List of available pluralization values:
zeroonetwofewmanyother
Substitutions
Substitutions are used to replace placeholders in the translation with dynamic values.
{
"sourceLanguage" : "en",
"version": "1.0",
"strings" : {
"%d of %d left" : {
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
"value" : "%d of %#@left@"
},
"substitutions" : {
"left" : {
"formatSpecifier" : "d",
"variations" : {
"plural" : {
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "%@ left"
}
}
}
}
}
}
},
"es" : {
"stringUnit" : {
"state" : "translated",
"value" : "%d de %#@left@"
},
"substitutions" : {
"left" : {
"formatSpecifier" : "d",
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "translated",
"value" : "%@ queda"
}
},
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "%@ quedan"
}
}
}
}
}
}
}
}
}
}
}
In the example above, the %d of %d left key has substitutions for the left placeholder in the English and Spanish languages.
Substitutions are currently not supported in the SimpleLocalize translation editor, but this feature is planned for the future.
Multi-file support
If you split translations in your application into multiple files, and you want to manage them separately in SimpleLocalize. Then you can use namespaces, that will allow you to group translations into separate files, and manage them in the translation editor.
Import & Export
SimpleLocalize supports an importing and exporting XC Strings file format via the SimpleLocalize CLI, which allows you to automate the process of keeping translations in sync with your application.
Import XC Strings
Example of importing XC Strings file format to SimpleLocalize using the CLI.
# Single file
simplelocalize upload --apiKey <PROJECT_KEY> \
--uploadFormat localizable-xcstrings \
--uploadPath ./Localizable.xcstrings
# Multiple files (namespaces)
simplelocalize upload --apiKey <PROJECT_KEY> \
--uploadFormat localizable-xcstrings \
--uploadPath ./Localizable-{ns}.xcstrings
Learn more about SimpleLocalize CLI and translations upload feature.
Add
--overwriteflag to update existing translations in SimpleLocalize from the imported file. Otherwise, only new translations will be added.
Export translations to XC Strings
Example of exporting translations from translation editor to XC Strings file format using the CLI.
# Single file
simplelocalize download --apiKey <PROJECT_KEY> \
--downloadFormat localizable-xcstrings \
--downloadPath ./Localizable.strings
# Multiple files (namespaces)
simplelocalize download --apiKey <PROJECT_KEY> \
--downloadFormat localizable-xcstrings \
--downloadPath ./Localizable-{ns}.strings
Learn more about SimpleLocalize CLI and translations download feature.