Step-by-step guide for localizing plurals in iOS

If you are already familiar with localizing plurals in iOS and you are just looking to remember the specifics, the cheat sheet below will help you out.

If you are new to this, skip the cheat sheet for now and read the basics below.

Cheat sheet

Cheatsheet for localizing plurals in iOS

Basics

Every time you want to localize texts like My dog ate 2 carrots where the carrot count is dynamic, one localization string will not be enough. For example, localizing with My dog ate %i carrots would produce My dog ate 1 carrots when passing in 1.

The first solution that may come to your mind could be to create another localization string for one carrot and adding some logic to your code like:

if carrotCount == 1 {
    label.text = NSLocalizedString("dog_eating_carrots_one")
} else {
    label.text = String(format: NSLocalizedString("dog_eating_carrots_multiple"), carrotCount)
}

Capture HTTP(s) traffic with Proxyman

Proxyman - Your ultimate man-in-the-middle proxy to effortlessly capture, inspect, and manipulate HTTP(s) traffic on macOS, Windows, iOS, and Android devices.

Get started for free

This solution may work for some languages, but different languages vary in how they handle plurals. For example, in Russian you would have to handle more cases. Plural rules for the word dog look like this:

• собака for 1, 21, 31, 41, 51, 61 etc. Examples: 1 собака, 21 собака
• собаки for 2-4, 22-24, 32-34 etc. Examples: 2 собаки, 22 собаки
• собак for 5-20, 25-30, 35-40 etc. Examples: 5 собак, 20 собак

It would be complicated to handle this logic in code. So here comes Localizable.strigsdict to the rescue.

Unlike a Localizable.strings file, a Localizable.strigsdict file provides additional features to work with different languages, for example to define plural rules. The Localizable.strigsdict is able to interpret the arguments you pass in and select the right localized string based on it.

Creating and localizing a Localizable.stringdict file

To create a Localizable.stringdict file select a .stringdict template from Xcode's dialog when creating a new file.

Creating a .stringdict file

The localization process is exactly the same as for Localizable.strings files. If you are new to localization in iOS in general, you can catch up by reading this localization guide.

Adding plural configuration

Now, you can add the plural configuration for the specific language. The template gives you a good starting point.

The .stringdict template

The configuration for our example could look like this:

A .stringdict configuration example

Let's go through it step by step.

1. Localized String Key — should be replaced with the key that you will use when calling NSLocalizedString. In our example the key is dog_eating_carrots.

2. NSStringLocalizedFormatKey

   • The value is the localized text with parameters. In our case it's My dog ate %#@carrotsCount@.
   • Every variable you define should be preceded by %#@ and followed by @
   • You only need to define variables for parameters where plural rules should be applied
   • If you just want to pass something like the dog's name, you can simply use the string format specifiers you already know like %@, %d etc. To pass the dog's name, our format string would look like this: My dog %@ ate %#@carrotsCount@.

3. Variable — the rules dictionary that applies to a specific variable. You create one for every variable you defined in NSStringLocalizedFormatKey. In our example, it's one variable with the name carrotsCount.

4. NSStringFormatSpecTypeKey — parameter processing rule. It's already set to NSStringPluralRuleType so we can leave it as is.

5. NSStringFormatValueTypeKey — specifies the format of the parameter like d for integer or f for double. For the full list, you can look into Apple's string format specifiers.

6. CLDR Language Plural Rules — You can choose different plural rules like zero, one, two, few, many and other. For some languages like English you only need to configure two rules, one and other . Other languages have only a single plural rule and some languages have more than two. A detailed guide is provided by CLDR.

Switching between property list and source code

Xcode provides a user interface to work with property list files. Depending on your preferences, you can also directly work with the source code. To switch, right-click on the Localizable.stringdict file and choose Open as -> Source Code. Switching back is the same with Open as -> Property List.

Here is the code for our example from above:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>dog_eating_carrots</key>
    <dict>
        <key>NSStringLocalizedFormatKey</key>
        <string>My dog ate %#@carrotsCount@.</string>
        <key>carrotsCount</key>
        <dict>
            <key>NSStringFormatSpecTypeKey</key>
            <string>NSStringPluralRuleType</string>
            <key>NSStringFormatValueTypeKey</key>
            <string>d</string>
            <key>zero</key>
            <string>no carrots</string>
            <key>one</key>
            <string>1 carrot</string>
            <key>other</key>
            <string>%d carrots</string>
        </dict>
    </dict>
</dict>
</plist>

Conclusion

Now that you are familiar with plurals localization, you can jump back to the cheat sheet on the top of the article and look at another example with 2 variables. To get fast results, you can just copy the souce code und paste it into your .stringsdict file as a starting point.

Capture HTTP(s) traffic with Proxyman

Proxyman - Your ultimate man-in-the-middle proxy to effortlessly capture, inspect, and manipulate HTTP(s) traffic on macOS, Windows, iOS, and Android devices.

Get started for free