|
File Extensions |
.xcstrings |
|
API Extension |
strings_catalog |
|
Import |
Yes |
|
Export |
Yes |
|
Plural forms support |
Yes |
|
Description support |
Yes |
|
Format options |
No |
Apple Strings Catalog (.xcstrings) is a localization format introduced in Xcode 15. It enhances the way developers manage localized strings by supporting structured formats for handling pluralization, device-specific variations, and more. This format is becoming the recommended approach for managing localizations in iOS and macOS application.
Code Sample
{
"sourceLanguage": "en",
"strings": {
"Sync Warning": {
"comment": "Sync function unavailable message",
"localizations": {
"en": {
"stringUnit": {
"state": "translated",
"value": "Cloud Sync must be enabled to use this feature."
}
},
"fr": {
"stringUnit": {
"state": "translated",
"value": "La synchronisation cloud doit être activée pour utiliser cette fonction."
}
}
}
},
"Chosen Collections": {
"comment": "View title indicating selected photo collections",
"localizations": {
"fr": {
"variations": {
"plural": {
"one": {
"stringUnit": {
"state": "translated",
"value": "%ld collection sélectionnée"
}
},
"other": {
"stringUnit": {
"state": "translated",
"value": "%ld collections sélectionnées"
}
}
}
}
},
"en": {
"variations": {
"plural": {
"one": {
"stringUnit": {
"state": "translated",
"value": "%ld Collection Selected"
}
},
"other": {
"stringUnit": {
"state": "translated",
"value": "%ld Collections Selected"
}
}
}
}
}
}
},
"Settings Hub": {
"localizations": {
"es": {
"stringUnit": {
"state": "translated",
"value": "Centro de configuración"
}
}
}
}
},
"version": "1.0"
}
When using the Phrase CLI, file exports follow the structure defined in the .phrase.yml configuration file. To ensure multiple languages are exported into a single .XCSTRINGS file during pull operations:
-
Specify only one file target in the CLI configuration file.
-
Use the
locale_idsparameter to list all the language locales included in the export.
Example .phrase.yml configuration
pull:
targets:
- file: ./i18n-test/Localizable.xcstrings
params:
locale_id: en # Main language for the download
locale_ids: # Additional languages to include
- de
- es
- fr
file_format: strings_catalog
Device variations
Apple Strings Catalog supports device variations, which allow different translation contents for the same key depending on the Apple device being used.
To handle device variations in Phrase Strings, separate keys are created for each device using the separator |==|. When importing .XCSTRINGS files, the device type is added to the base key name using this separator.
Example
The key named %lld Product(s) Ordered for the applewatch device is imported as a plural key named %lld Product(s) Ordered|==|device.applewatch into Phrase Strings.
During export, Phrase Strings detects the device variant using the separator and restores its original nested structure for Apple’s localization format.
{
"sourceLanguage": "en",
"strings": {
"%lld Product(s) Ordered": {
"comment": "Indicates the number of products ordered, with device-specific variations",
"localizations": {
"en": {
"variations": {
"device": {
"applewatch": {
"variations": {
"plural": {
"one": {
"stringUnit": {
"state": "translated",
"value": "%lld Product ordered (Apple Watch)"
}
},
"other": {
"stringUnit": {
"state": "translated",
"value": "%lld Products ordered (Apple Watch)"
}
}
}
}
},
"ipad": {
"variations": {
"plural": {
"one": {
"stringUnit": {
"state": "translated",
"value": "%lld Product ordered (iPad)"
}
},
"other": {
"stringUnit": {
"state": "translated",
"value": "%lld Products ordered (iPad)"
}
}
}
}
},
"iphone": {
"variations": {
"plural": {
"one": {
"stringUnit": {
"state": "translated",
"value": "%lld Product ordered (iPhone)"
}
},
"other": {
"stringUnit": {
"state": "translated",
"value": "%lld Products ordered (iPhone)"
}
}
}
}
},
"mac": {
"variations": {
"plural": {
"one": {
"stringUnit": {
"state": "translated",
"value": "%lld Product ordered (Mac)"
}
},
"other": {
"stringUnit": {
"state": "translated",
"value": "%lld Products ordered (Mac)"
}
}
}
}
}
}
}
},
"fr": {
"variations": {
"plural": {
"few": {
"stringUnit": {
"state": "translated",
"value": "%lld produit(s) commandé(s)"
}
},
"many": {
"stringUnit": {
"state": "translated",
"value": "%lld produits commandés"
}
},
"one": {
"stringUnit": {
"state": "translated",
"value": "%lld produit commandé"
}
}
}
}
}
}
}
}
}
String substitutions
Apple Strings Catalog supports string substitutions that provide flexible placeholders for dynamic content.
To handle string substitutions in Phrase Strings, separate keys are created using the separator |==|. When importing .XCSTRINGS files, the substitution is added to the base key name using this separator.
Example
The key named birdSightingAlert for the BIRDS substitution is imported as a plural key named birdSightingAlert|==|substitution.BIRDS into Phrase Strings.
During export, Phrase Strings detects the substitution using the separator and restores its original nested structure for Apple’s localization format.
"birdSightingAlert": {
"comment": "Alert message indicating the number of birds spotted",
"localizations": {
"en": {
"stringUnit": {
"state": "new",
"value": "You spotted %#@BIRDS@!"
},
"substitutions": {
"BIRDS": {
"formatSpecifier": "BIRDS",
"variations": {
"plural": {
"one": {
"stringUnit": {
"state": "new",
"value": "a bird"
}
},
"other": {
"stringUnit": {
"state": "new",
"value": "several birds"
}
},
"zero": {
"stringUnit": {
"state": "new",
"value": "no birds"
}
}
}
}
}
}
}
}
}