# Apple Strings Catalog
> All Apple SDK localization format
URL: https://store.crowdin.com/string_catalog
Category: File Formats
Type: System
Author: Awesome Crowdin
Apple Strings Catalog is a natively supported file format, you can use it without an additional installation. Just upload it to your projects and start the localization.
## File Format Details
| Attribute | Value |
| --------- | ----- |
| File Extension | .xcstrings |
| [API Type](https://developer.crowdin.com/api/v2/#operation/api.projects.files.post) | string_catalog |
| Source can be edited in Crowdin | Yes |
| Generating translated files via [Bundles](https://support.crowdin.com/bundles/) | [Search Crowdin Store](https://store.crowdin.com/tags/string-exporter) |
| Supports pluralization | Yes |
| WYSIWYG Preview in the editor | No |
| Supported types of contextual information | Text comments, Screenshots, Live preview via SDK |
| Custom attributes | No |
| Existing translations import possibility | Key-value mapping |
## Sample File
```json
{
"sourceLanguage" : "en",
"strings" : {
"welcomeMessage" : {
"comment" : "Regular string",
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "new",
"value" : "Welcome to the app!"
}
},
"uk" : {
"stringUnit" : {
"state" : "translated",
"value" : "Ласкаво просимо до застосунку!"
}
}
}
},
"welcomeMessageDI" : {
"comment" : "Device-specific string",
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "new",
"value" : "Welcome to the iPhone app!"
}
}
}
},
"daysRemaining" : {
"comment" : "Plural string",
"localizations" : {
"en" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "new",
"value" : "1 day remaining"
}
},
"other" : {
"stringUnit" : {
"state" : "new",
"value" : "%d days remaining"
}
}
}
}
}
}
},
"notifications" : {
"comment" : "Plural string with zero plural form",
"localizations" : {
"en" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "new",
"value" : "1 notification"
}
},
"other" : {
"stringUnit" : {
"state" : "new",
"value" : "%d notifications"
}
},
"zero" : {
"stringUnit" : {
"state" : "new",
"value" : "No notifications"
}
}
}
}
}
}
},
"itemsInCart" : {
"comment" : "Device-specific plural string",
"localizations" : {
"en" : {
"variations" : {
"device" : {
"ipad" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "new",
"value" : "1 item in your cart"
}
},
"other" : {
"stringUnit" : {
"state" : "new",
"value" : "%d items in your cart"
}
}
}
}
}
}
}
}
}
},
"unreadMessages" : {
"comment" : "Device-specific plural string with zero plural form",
"localizations" : {
"en" : {
"variations" : {
"device" : {
"mac" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "new",
"value" : "1 unread message on your Mac"
}
},
"other" : {
"stringUnit" : {
"state" : "new",
"value" : "%d unread messages on your Mac"
}
},
"zero" : {
"stringUnit" : {
"state" : "new",
"value" : "No unread messages on your Mac"
}
}
}
}
}
}
}
}
}
},
"welcomeUser" : {
"comment" : "String with variable and substitution strings",
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "new",
"value" : "Welcome, %#@USERNAME@!"
},
"substitutions" : {
"USERNAME" : {
"formatSpecifier" : "USERNAME",
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "new",
"value" : "user"
}
},
"other" : {
"stringUnit" : {
"state" : "new",
"value" : "users"
}
},
"zero" : {
"stringUnit" : {
"state" : "new",
"value" : "no users"
}
}
}
}
}
}
}
}
}
},
"version" : "1.0"
}
```
## Translating Apple Strings Catalog
**Adding Source Strings to String Catalog Files**
String Catalog is one of the formats that allows you to edit (add, delete, and modify) source strings directly in Crowdin. Thus, you can add new strings to your String Catalog files without updating the source file via **Content > Files**.
**Adding Regular Source Strings**
1. Open your project and go to **Content > Strings**.
2. Click **Add String**.
3. In the appeared dialog, select the source file from the **Files** list.
4. Fill in the **String** and **Identifier** fields.
5. (Optional) Add string context, labels, and set the maximum length for the translated text.
6. Click **Add**.
**Adding Plural Source Strings**
1. Open your project and go to **Content > Strings**.
2. Click **Add String**.
3. In the appeared dialog, select **Plurals**.
4. Select the source file from the **Files** list.
5. Enter text for each plural form based on your project’s source language requirements.
6. In the **Identifier** field, specify a unique key using the format `stringIdentifier|==|plural`.
7. (Optional) Add string context, labels, and set the maximum length for the translated text.
8. Click **Add**.
The plural string will be added to your String Catalog source file, including default plural forms (e.g., `one` and `other` for English).
**Adding Zero Plural Form**
If your project requires the `zero` plural form in addition to the default plural forms, you can add it as a single string with the identifier format: `stringIdentifier|==|plural.zero`.
**Adding Device-specific Strings**
To create strings specific to certain devices, use the following identifier format: `stringIdentifier|==|device.mac`
- **stringIdentifier**: unique string identifier (key)
- **device.mac**: device-specific type, where `mac` is an example device
Supported Device Types:
- appletv
- applevision
- applewatch
- ipad
- iphone
- ipod
- mac
- other
**Adding Device-specific Plural Strings**
To add a device-specific plural string, use the following identifier format: `stringIdentifier|==|device.mac.plural`
To include a `zero` plural form for device-specific strings, use: `stringIdentifier|==|device.mac.plural.zero`
**Adding Strings with Variable and Substitution Strings**
If your string contains a variable, you’ll need a substitution string to define the variable’s format.
String with variable:
- **welcomeUser**: unique identifier (key)
- **Welcome, %#@USERNAME@!**: the source text with a variable placeholder
### To Add Substitution Strings:
1. Create the substitution string with an identifier in this format: `welcomeUser|==|substitutions.USERNAME`
2. (Optional) For a `zero` plural form of a substitution, use this format: `welcomeUser|==|substitutions.USERNAME.zero`
**Note:** A substitution string can only be added if a primary string containing the variable exists in the file (e.g., a string with the argument `%#@USERNAME@` must be present to add a substitution string for `USERNAME`).
**Plural Forms**
In some cases, your source files may contain source strings with the Zero plural form, even if your Crowdin project's source language does not support the Zero plural form (e.g., English supports only the One and Other plural forms).
When importing such files to Crowdin, the Zero plural form will be imported as a separate string, while the rest of the plural forms will be combined into a single plural string.
When exporting translations for target languages that natively support the Zero plural form, this separately imported Zero plural form string will be ignored and not exported. To prevent duplication, Crowdin will export only the Zero plural form created by Crowdin.
When exporting translations for target languages that do not natively support the Zero plural form, this separately imported Zero plural form string will be exported in the translation file.
Read more about Translating Strings with Plural Forms.
**Note:** Crowdin follows the CLDR Language Plural Rules when working with plural forms. Including the Zero plural form in source files is only recommended if your Crowdin project's source language supports it natively.
**Exporting Translations for Primary and Dialect Languages**
In Crowdin, some languages are considered primary (e.g., English, French, Spanish, etc.), while others are considered dialect languages (e.g., English, Canada; French, Canada; Spanish, Latin America, etc.), which are based on the primary languages. Depending on your Crowdin project's target language list, the language codes used in the exported translation files may be applied in the following way:
* If your Crowdin project contains only primary languages with no dialect languages, on export, Crowdin will apply two_letters_code language codes to all project's target languages.
* If your Crowdin project contains both primary languages and dialect languages that share the same two_letters_code language code, in this case, on export, Crowdin will apply locale language code to dialect languages.
* If your Crowdin project contains two primary languages that share the same two_letters_code language code, like in the previous case, on export, Crowdin will apply locale language code to these languages.
**Setting up Language Mapping and Creating Custom Languages**
There might be cases when the language codes for particular languages differ in Crowdin from the ones you use in Xcode. To ensure that exported translations from Crowdin will be successfully imported into Xcode, we recommend setting up Language Mapping or creating Custom Languages.
See the examples below:
* In Xcode, you have Chinese, Chinese Simplified, and Chinese Traditional. Since there is no Chinese among the supported Crowdin languages, in this case, you can add Chinese Simplified and Chinese Traditional to your Crowdin project and create an additional custom language for Chinese, which you can then also add as one of the target languages.
* In Xcode, you have Chinese and Chinese Traditional. In this case, you can add Chinese Simplified and Chinese Traditional to your Crowdin project and use the language mapping to change the language code for Chinese to the same one you use in Xcode.
## Syncing the Apple Strings Catalog with Crowdin CLI
To properly upload and download **Apple Strings Catalog** files using the Crowdin CLI, you need to add specific configuration to your `crowdin.yml` file.
This is necessary because the Strings Catalog format (`.xcstrings`) is a multilingual file type, meaning it contains strings for multiple languages in a single file, unlike the older `.strings` format which had one file per language.
For a detailed explanation and configuration examples, refer to the Crowdin documentation on [Multilingual Files](https://crowdin.github.io/crowdin-cli/advanced#multilingual-files).