Apple Strings Catalog translation with 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

Sample File

{
    "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.