iOS localization: Step-by-step Guide

The process of iOS localization is often tedious and unorganized. Lokalise is here to help you solve this problem! In this tutorial, we’ll focus on enabling localization in your iOS application as well as adding, managing, and integrating translations in your project.

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

This post was initially written in 2018 and updated in 2021 by Fedya Levkin and Ilya Bodrov-Krukowski.

Part I: Setting up your app

Step 1: Create Localizable.strings file

Localizable.strings stores application 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 Ctrl+N or Cmd+N. Search for strings and you will see Strings File in Resource window:

 

Choose Strings File and name the file Localizable:

 

Now, let’s select Localizable.strings file in the Navigator. In Utilities, you will see localization panel.

Click Lokalize… and continue to next step.

Step 2: Adding languages

Let’s add some languages to the application and create .strings files for each language.

Select your root project file, and then proceed to the project panel. Find the Localization section section, click the “plus” (+) icon, and add the desired languages. Select only the Localizable.strings file for localization. In this tutorial we’ll add German and Russian languages.

 

In the Choose files and reference language… dialog select the Localizable.strings file for Localization (we are not covering .storyboard localization in this post):

 

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

Step 3: Working with translations

So, our Localizable.strings files are ready, therefore let’s populate these. As mentioned before, the localization process involves keys and values. Key is a unique identifier that is used in the source code; when the application is served to the user, keys are replaced with the corresponding translations for the language set by the user. Let’s add two entries into the .strings files:

Localizable.strings (English):

"welcome_screen_title" = "Welcome";
"login_button" = "Log in";

Localizable.strings (German):

"welcome_screen_title" = "Willkommen";
"login_button" = "Einloggen";

Localizable.strings (Russian):

"welcome_screen_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, String(localized:) or a custom shortcut method. Modify the application(_:, didFinishLaunchingWithOptions:) method of your delegate to test-drive the localization system:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
  print(NSLocalizedString("welcome_screen_title", comment: ""))        
  print(String(localized: "login_button")) // New in Xcode 13
  print("""
\("welcome_screen_title"~)

\("login_button"~)
""")
        
  return true
}

Hurray! You should get multiple statements printed in the console.

Tip #1: The shortcut

Typing NSLocalizedString("key", comment: "comment") every time is tedious and make your code look heavier and harder than it needs to be. To make your life easier you can implement a custom post-fix operator:

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

Tip #2: Easy testing

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

Then under the Options tab select Application Language that you want to test:

Part II: Managing translations

Now your application is set up and you know the basics of localization process on iOS, so let’s 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 a project in Lokalise

Once you sign up to Lokalise (you can grab a free 14-days trial, no credit card is required), just tap the New project button (or explore the Sample Project if you wish to get more familiar with Lokalise features first). Give your project a name and optionally a description. You can modify the base language setting later if you change your mind about it.

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

 

Step 2: Upload your files or add new keys

To import your .strings file to Lokalise, click Upload in the top menu and drag Localizable.strings to the drop area. Alternatively, you can translation keys manually in your project.

 

Step 3: Invite team members

Getting localization work done quick requires a team of contributors. Switch to the Contributors section by clicking the icon in the project’s icon bar and start adding teammates. Any user can be granted admin privileges, i.e. the same rights on the project as you. If a user is not an 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. Feel free to explore the Sample Project or just take a peek at our Documentation to read about the basic concepts and options.

 

 

Part III: Integrating with your project

Finally, the translation part is done. Now, how do you get the texts out of Lokalise and make it usable in your app? There are three main options, so choose the one you prefer:

Option 1: Download the files via GUI

Click the Download icon in your project icon bar and select Apple Strings as the exporting format. Click Build and download to get the translation bundle. Then move .lproj folders from the downloaded archive into your project replacing the existing localization. That’s it!

 

Option 2: Use API or CLI tool

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

 

Option 3: Integrate using Lokalise iOS SDK

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

The displayed logo is is a trademark of Apple Inc. Lokalise is an independent product and has not been authorized, sponsored, or otherwise approved by Apple Inc.

Conclusion

So, in this article we have seen how to get started with iOS localization and how to manage translations with Lokalise. Please don’t hesitate to reach us out if you have any further questions!

Related posts

Sign up to our newsletter

Get the latest articles on all things data delivered straight to your inbox.

Read also
Localization made easy. Why wait?
The preferred localization tool of 2000+ companies