Localisation

Localisation in iOS SwiftUI

Learn how to adapt your iOS app to other languages

Localisation is the process of making your app support another language. Adopting new languages is one of the easiest way to increase the market audience of your app.

There are more factors to take into account when targeting an audience from another region other than the language. For example in Arabic they read and write right-to-left where as in Latin based languages they do it left-to-right.

The purpose of this tutorial is to show you how to support a new language in your iOS SwiftUI app. Other factors such as writing orientation are out of scope of this article.

In this article we’ll start by creating a new iOS SwiftUI application. The app created from template displays “Hello, world!”. We’ll take the template based app and add support for Spanish. Our app will then display “Hola mundo!” when the users preferred language is set to Spanish.

We’ll take a deep dive into the app structure to see what are the implications of supporting multiple languages in our apps and how the localisation works at runtime.

For this post I assume you know the very basics of SwiftUI and the basics of iOS and Swift.

I have used Swift 5.2.4 and Xcode 12.0 beta whilst writing this article.

How to support a new language

In this section we’ll create a new SwiftUI app from scratch. We’ll then localise the app to Spanish.

We will:

  1. Create a new SwiftUI app
  2. Add Spanish support to the project
  3. Add Spanish translation in the app
  4. Adapt the app to use the correct language at runtime

1. Create a new SwiftUI app

Let’s begin by creating a new SwiftUI app for iOS. Open Xcode and then from menu select File > New > Project…

Next from iOS template select App. Click Next.

Then on “Choose options for your new project” prompt call the app SwiftUILocalisation. Make sure the “Interface:” option is SwiftUI, “Life Cycle:” is SwiftUI App and finally the “Language:” is set to Swift. All checkboxes can be left unchecked. Click Next.

Then navigate to a folder where you’d like to store your project. Finally click Create.

2. Add Spanish support in the project

The first step to support a new language in your app is to configure the entire project Localisations settings. This will tell Xcode that all targets within the project are to support Spanish.

Open the project navigator, from menu select View > Navigators > Project. Next click on the SwiftUILocalisation with the blue icon on project navigator pane.

Then under PROJECT select the SwiftUILocalisation project traget.

Next under the Info tab Localizations section click the plus icon (+) to add a new language.

Then from the list select Spanish (es).

With this our app now ready to support Spanish.

3. Add Spanish translation in the app

From template your project has file named ContentView.swift which contains the following code:

struct ContentView: View {
var body: some View {
Text("Hello, world!").padding()
}
}

The code above has the text “Hello, world!” harcoded. This means the text “Hello, world!” won’t change at runtime.

To support our hello world message in both English and Spanish we need to retrieve the message in the correct language at runtime.

We need some mechanism to first know which languages the user prefers. Then we need to display the app in the language which the user prefers most. That is if they both prefer Spanish and English — in that order — then we must display the app in Spanish. Once we know which language we must display we must then fetch the correct values for that language.

Sounds complicated? Worry not. Apple offers a very simple mechanism that does all of that for us in a single function call!

First we’ll add a new strings file to the project. From menu select File > New > File…

From template search and select for Strings File then click Next.

The strings file will contain the values for a specific language. We’ll have a strings file per language. However for now we’ll create only a single file.

Next name the file Localizable then click Create.

Once Localizable.strings is open add the following line to it:

"hello_world" = "Hello, world!";

This file will be used for the English language support in the app.

Next from menu select View > Inspectors > File. On the right hand side of Xcode a pane will open up (if not already open). Then click on the Localize… button on the file inspector pane under Localzation section.

When prompted “Do you want to localize this file?”, select English from the dropdown menu and then click Localize.

What we have done in the previous action is tell Xcode that the Localizable.strings file is file used for localisation. Specifically we have told Xcode that the file we created is the English translation of the app. Furthermore Xcode will create a folder named en.lproj in our project and move the Localizable.strings their.

The project structure before Localizing the file:

SwiftUILocalisation
├── SwiftUILocalisation
│ ├── ...
│ ├── Localizable.strings
...

After:

SwiftUILocalisation
├── SwiftUILocalisation
│ ├── ...
│ └── en.lproj
│ └── Localizable.strings
...

On the right hand side pane under Localization section you’ll notice a change.

Where before we had a button now we have the languages supported. Currently there is only Localizable.strings file for English. Next let’s support Spanish. Check the Spanish box in the File inspector pane under the Localization section.

With this Xcode will automatically create a folder named es.lproj that will contain all the localized files for the Spanish support. Furthermore Xcode will create automatically a Localizable.strings file inside it.

Project structure after including Spanish localisation for the Localizable.strings file:

SwiftUILocalisation
├── SwiftUILocalisation
│ ├── ...
│ ├── en.lproj
│ │ └── Localizable.strings
│ └── es.lproj
│ └── Localizable.strings
...

Next let’s add the Spanish translation. Go over to the project navigation pane on the left side of Xcode (from menu select View > Navigators > Project). Notice Localizable.strings file has a disclosure icon. Click on the icon and Xcode will disclose Localizable.strings (English) and Localizable.strings (Spanish) files under Localizable.strings. Click on Localizable.strings (Spanish).

Next change the value for the hello_world key to Hola mundo!.

4. Adapt the app to use the correct language at runtime

Next we’ll make use of the strings file created in the previous step. Currently our code renders the text “Hello, World!” which is specified in code. Here we want to tell the system to retrieve the hello_world message localised for the users preferred language. If none of the users preferred language is supported by the app then the system will use the app’s base language (English).

Open ContentView.swift. Then change the following code:

struct ContentView: View {
var body: some View {
Text("Hello, world!").padding()
}
}

to:

struct ContentView: View {
var body: some View {
Text(NSLocalizedString("hello_world", comment: "")).padding()
}
}

The function NSLocalizedString is the mechanism offered by Apple to ease the selection and display of the most appropriate language for the individual user. NSLocalizedString function will first solve which language to use and then fetch the value for hello_world key from the language specific Localizable.strings file.

Note you can use a different file name other than Localizable.strings file if you prefer. However you’ll have to specify the tableName parameter of the function. The default file name NSLocalizedString function will look for is Localizable.strings.

Run the app in a simulator. To test out Spanish change the simulator language to Spanish and see the effect.

Summary

In this tutorial we learnt:

  • how to localise an app
  • how to add and fetch translations for a key

Final notes

You can find the full source code for this tutorial in my Github repository:

There hasn’t been any change on how to localise your app from UIKit to SwiftUI using the NSLocalizedString function. However with UIKit you also have the option to do Storyboard localisation. I still use UIKit on day to day basis however I do not make use of Storyboards since I do not prefer them in a complex projects.

For more on iOS development follow me on Twitter or Medium!

Senior iOS Engineer @ Onfido. Writing weekly blogs on iOS and programming. Follow me to stay tuned!

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store