Overview

Internationalization (or i18n) basically describes the process of preparing your app for localization (or l10n). It is all about adjusting your code and design in a way that makes the text easily exchangeable.

If you are using Xcode 7 it is easy to internationalize your app by using base internationalization, which should be activated by default for newer Xcode versions. Base internationalization separates your user-facing strings from your .storyboard and .xib files.

Not all user-facing strings are stored in your .storyboard and .xib files. To get your hard coded strings easily localized you have to use the NSLocalizedString Foundation macro when coding text. This will return a localized version of the string – if available.

NSLocalizedString is typically followed by 2 arguments, the first one being the key, and the second one being a comment to provide further context. The comment is not mandatory and can be replaced with nil.

Here are several examples of how to implement NSLocalizedString:


String in Swift

_userCount.text = [NSString stringWithFormat:@"There are %@ users registered"];

Internationalized

var helloWorld = NSLocalizedString("Hello World!", comment: "welcome message");

String in Objective C

var helloWorld = "Hello World!";

Internationalized

_userCount.text = [NSString stringWithFormat:NSLocalizedString(@"There are %@ users registered", nil];

String in Objective C

NSString *welcome = @"Welcome to LingoHub!";

Internationalized

NSString *welcome = NSLocalizedString(@"Welcome to LingoHub!", @"A welcome message");

Tutorial

This tutorial is split up into 2 sections to show you how to set up your project for internationalization.

I. ACTIVATE BASE INTERNATIONALIZATION

Step 1: Select your project target in the project folder.

Step 2: Click the Info button.

Step 3: Click if Use Base Internationalization is activated. Activate if necessary.

Step 4: Click the icon to add all the languages you want to support.

Step 5: After selecting a language you will have to pick the resource you want to localize and click Finish.

Step 6: To add additional resources afterwards, pick the resource you want localized and click the Localize… button in the localization section within the file inspector.


II. INTERNATIONALIZE STRINGS

Assuming you have user-facing text stored in your code, you have to use the NSLocalizedString Foundation macro to internationalize it.

Step 1: Localize text in your code.


Objective C

NSString *helloworld = @"Hello World!";

Swift

var helloWorld = "Hello World!";

Step 2: Implement the NSLocalizedString macro.


Objective C

NSString *helloworld = NSLocalizedString(@"Hello World!", nil);

Swift

var helloWorld = NSLocalizedString("Hello World!", comment: "welcome message");

More examples on how to use the NSLocalizedString macro can be found in the Overview.

Step 3: Once you are done modifying your strings in the code, you can use the genstrings script to create a Localizable.strings file for your development language if it doesn’t exist already.

Open the terminal and use the following commands:


Objective C

cd [Project Folder]
find . -name *.m | xargs genstrings -o .

Swift

cd [Project Folder]
genstrings *.swift

This script will create a Localizable.strings file in the root directory of your project and add the key-value pair as well as the comment for every occurrence of NSLocalizedString to Localizable.strings.

This file should be added to your project and then activated for localization following the steps described in Step 6 of section I.

You can now send the .strings files you want translated to your translator!
The localized files then need to be imported into the respective .lproj folder of the language.


Tips and Tricks

Provide Context in Comments

You can start localizing as soon as your text is in a resource file. Translators might struggle with these files and they have no experience in handling resource files. To avoid incorrect translations and misconceptions provide your translators with ultimate context information. This information can be added as comments when adding the NSLocalizedString macro in your code, or in the .strings file directly.

Include context information about the location on the screen or phrasing for example in your comments.

Hint
Provide the ultimate context information if text is included in a button or has character limitation.

NSString *welcome = NSLocalizedString(@"Welcome to LingoHub!", @"A welcome message");

var helloWorld = NSLocalizedString("Hello World!", comment: "A welcome message");

// Sign Up button in the top right corner of the website, max. 20 characters
"button.signUp"="Sign Up";

Hint
LingoHub detects comments included in your resource file automatically and includes them upon import. Comments are then displayed on the Online Editor providing your translators with helpful information on translations.
Besides comments you can add LingoChecks (quality checks) to your resource file too. They are as well included upon import and automatically check translations for text length, placeholders, terms and more.
Learn more about LingoChecks in our documentation.

// lh-check: {min: 20}
"button.signUp"="Sign Up";

Use Auto Layout

Auto Layout is a useful function to dynamically adjust your application to different kinds of external and internal changes.
An example for an external change is the rotation of your device, and an internal change might be internationalization, i.e. a different language is displayed.

When it comes to internationalization Auto Layout will automatically adjust your design not only to more verbose languages, but also to RTL (right-to-left) languages.

Text might appear cropped when using fixed width constraints. In case this problem occurs removing fixed width constraints will solve it.


iOS i18n - use Auto Layout

The default behavior for text fields and labels is to resize automatically. If a view is not adjusting accordingly, just select it and then click Editor followed by Size To Fit Content.

When adding horizontal constraints, use leading and trailing instead of left and right. This will enable RTL support, as these two attributes will display the text according to the locale from either left to right or vice versa.
Even without localizing your application any further this will satisfy the needs of the majority of RTL users.

iOS i18n - using Auto Layout

Key Structure

It is common practice to use your development language content as key when using .strings files.

"Registration successful!"="Anmeldung erfolgreich!";
"Registration failed."="Anmeldung fehlgeschlagen."; 

This is not necessarily the best practice, but still often chosen, as it saves time in the beginning when you are internationalizing your application. It ultimately speeds up your internationalization process because you do not have to come up with key names.

Hint
If you are (or intend to) offering your application on Android as well, this approach is not be the best possible. Using LingoHub you can export your .strings resource files as .xml Android resource files at the push of a button (and vice versa).
In this case it is better to use generic keys.
Naming these keys is hard, so it is best not to overthink it. Making up complicated names for your keys will not be beneficial if you don’t know what the key is for the next day.

It is recommendable to name your keys after their purpose whether than using the text separated by underscores. That way the name of your key will stay relevant even when parts of your text change. Moreover, the key can include some valuable context information for your translators when naming it after its purpose.

"signUp.success"="We’ve just sent a confirmation link. Click it to activate your account.";
"signUp.failed"="Registration failed. Please review the information you entered and fix any errors."; 

Localize Images

Sometimes localizing your text is not enough. If you use images in your app they need to be localized as well.
If you use a picture of the A-Ok gesture it might be better to change it if you expand to Brazil as this is equally bad as raising the middle finger in the U.S.

To localize an image in Xcode 7 select it in the project navigator and bring up the file inspector. Here you will find a Localize… button which has to be clicked and confirmed. Afterwards you will find options for your other locales in the localization section to add localized versions of the image.


iOS i18n - localize images

Internationalize Info.plist

The Info.plist file contains lots of important information about your app, like the display name, so it is important not to disregard this file when thinking of localization.

The fast and dirty way to do this is by enabling localization like you do with any other resource file and then localize the content in Xcode.

If you want your Info.plist translated by a professional it is recommended to create a separate .strings file called InfoPlist.strings which contains all your Info.plist values which will then be localized into any target language.

"CFBundleDisplayName" = "$LOCALIZED_NAME";
"CFBundleName" = "$LOCALIZED_NAME";

This gives you the advantage of having everything stored in a .strings file which is easier to handle for professional translators.

Here is a quick guide about creating this file:


Step 1: Click on File – New – File …

iOS i18n - internationalize info.plist

Step 2: Pick Strings File.

Step 3: Name it InfoPlist.strings and click Create.

iOS i18n - internationalizing info.plist

Don’t forget your Numbers

We might drift away from iOS i18n and delve into the the topic of localization right now. Talking about localization helps you to be well prepared and makes sure you’re not missing out on anything. To top it off, this section covers the topic of localizing numbers.

Currencies and prices often cause irritation when localizing an application. Some currencies are listed before the number, like £, and some are listed afterwards, like €. This might be self explanatory, but never ever exchange the currency symbols and keep the prices the same (e.g. £100 – 100 €). This is extremely important as currencies have different conversion rates. Same goes for measuring lengths, weight, shoe sizes and many more. All these units are not standardized around the globe and have to be adjusted accordingly.

Read more interesting information in our Android i18n with Android Studio and Windows i18n with Visual Studio tutorials or discover some helpful localization insights on our blog.


Quick Summary

  • Exchange hard coded content with references to resources.
  • Use Auto Layout within Interface Builder to adjust the layout to localized text.
  • Add context information to your translations as comments.
  • Adapt the environment (images, colors, etc.) when localizing.
  • Consider more verbose languages in your design.

Try LingoHub 14 Days for free

Start your language project and get access to unlimited features.