Getting started with iOS localization

Updated 8 days ago ​by Fedya

Process of localisation is sometimes tedious and unorganized. Lokalise helps you solve this problem. In this tutorial, we’ll focus on enabling localisation in your application, adding, managing and integrating localisations in your project.

This tutorial is based on Xcode 8.2.1, it shows how to setup localisation from zero to hero and use Lokalise as the translation management platform. If you are a seasoned localisation master, we'd still recommend going through and take notes of some specific localisation details.

Part I: Setting up your app

Step 1: Create Localizable.strings

Localizable.strings stores app strings as key-value pairs for each language. Let's create this file for the base language first. Select File → New → File… or just tap ⌘-N. Search for stringsand you will get Strings File in Resource window.

Choose this option and name the file Localizable.

Now, lets select Localizable.strings in the Navigator. In Utilities you will see Localisation panel..

Click Localize… and select English from the dropdown menu.

Step 2: Adding languages

Let's add some languages and create .strings file for each of the languages.

Select your root project file, then project panel. Down in localisation section simply click + and add the languages you need. Select only Localizable.strings for localisation. We will add German and Russian for demo purposes.

Let’s find Localizable.strings using Navigator. Now you can expand it and see a Localizable.strings for every language.

Step 3: Working with localisations

Now once Localizable.strings files are ready, let's populate these. As mentioned earlier, localisation process involves keys and values. Key is usually an ID of the copy you want to put in place on elements. Let's add two entries into each of the .strings files.

Localizable.strings (English)

"welcome_sceen_title" = "Welcome";
"login_button" = "Log in";

Localizable.strings (German)

"welcome_sceen_title" = "Willkommen";
"login_button" = "Einloggen";

Localizable.strings (Russian)

"welcome_sceen_title" = "Добро пожаловать";
"login_button" = "Вход";

Once the keys are set up, let's learn how to get the translations for these. To do that we will use NSLocalizedString method. Modify application:didFinishLaunchingWithOptions:method of you delegate to test-drive the localisation system.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    print(NSLocalizedString("welcome_sceen_title", comment: ""))
    return true

Hurray! You should get Welcome printed in the console.

Tip #1: the shortcut

Typing NSLocalizedString(“key”, comment: “comment”) all the time will annoy you and make your code look heavier and harder than it needs to be. To make your life easier, choose one of two options:

Option 1. Add String extension

extension String {
    var localized: String {
        return NSLocalizedString(self, comment: "")

Option 2: Add postfix operator

postfix operator ~
postfix func ~ (string: String) -> String {
    return NSLocalizedString(string, comment: "")

Now NSLocalizedString("key", comment: "comment") becomes "key".localized or "key"~.

Tip #2: easy testing

You can change the language of your app by modifying your Scheme. Select your scheme and click Edit Scheme…

Then in Options tab select Application Language that you want to test.

Part II: Managing localisations

Now your application is set up and you know the basics of localisation process on iOS, so lets see what's the fuzz is all about. Imagine thousands of keys across tens of language files, making sure all are in sync, are translated and proofread. Pretty scary, huh? We've built Lokalise to help you avoid all the chaos.

Step 1: Create project in Lokalise

Once you sign up to Lokalise, just tap "Add another project" button (or explore the Sample Project if you wish to get more familiar with Lokalise features first). Give you project a name and optionally a descripotion. You can change base language setting later if you change your mind about it.

Each project has unique ID (you can see it in project settings), that is used when referring to a project over API.

Step 2: Upload your files or add new keys

Import your .strings file to Lokalise. Click upload and drag Localizable.strings to drop area. Alternatively, you can do it the other way – start by adding keys in Lokalise first.

Step 3: Invite team members

Getting localisation work done quick requires a team of contributors. Switch to Contributorssection by clicking the icon in the project's iconbar and start adding team mates. Any user can be granted admin privileges, i.e. the same rights on the project as you. If user is not admin, you can specify per-language access to the project specifying some languages as reference (read-only) or contributable (read and update). Only admins have access to key modification, importing, exporting, settings etc.

Step 4: Edit!

Lokalise editor is feature-packed. We've worked hard to deliver light and responsive interface while still offering all the features you would need while working with app or web project copy. Fell free to explore Sample Project or just take a look at Documentation to read about the basic concenpts and options.

Part III: Integrating with your project

Finally, the translation part is done. How to get the information out of Lokalise and make it usable in your app? There are four options, choose the one you prefer:

Option 1: Download the files

Click Download icon in your project iconbar and select Apple Strings as the exporting format. Click Build and download to finish and get the file. Then move .lproj folders from the downloaded archive into your project replacing the existing localisation, that's it.

Option 2: Use Fastlane actions we've built

If you are using Fastlane, then use lokalise.rb provided in this Github repository. Let us know in support chat if you have additional questions related to the action scripts.

Option 3: Use API or CLI tool

Depending on your project deployment setup you way want to use either Lokalise API or the CLI tool – both approaches give you a simple way to automatically generate and download localisation files.

Option 4: Integrate using Lokalise iOS framework

Using our framework gives an opportunity to update your app texts over-the-air without the need to resumbit for Appstore review. Please refer to Lokalise iOS framework instructions.

How did we do