Introduction to SwiftUI Localization tutorial

Updated Apr 21, 2021

SwiftUI Localization How-to

Localizing in SwiftUI follows the same pattern as localization of all apps in Xcode.

1. First, you need to identify the texts to be translated.
These are your user-facing text labels, buttons, and other visible parts of your app's user interface.
2. Then you need to add them to a localization file for your translators to work on.
At runtime, your iOS/Mac app will show the right translation to the user based on their own language preferences.

There are two ways you accomplish this: Using NSLocalizedString(), or creating a Localizable.strings file.

Both work equally well and it's more about personal preference. Let's discuss both methods.

Localization Q&A by Babble-on

More questions:

Translate that SwiftUI app

Once you've completed this tutorial to internationalize your app, please let us translate your strings!
Bookmark this page and come back for a free price quote.

Translate my app


Method 1: Using NSLocalizedString() for SwiftUI Localization

Wrap text in NSLocalizedString()

Let's start with a simple button, which might look like this in your SwiftUI code:

Button("Sign in", action: signIn)

We definitely want this button localized, so we add NSLocalizedString() around the literal text

 Button(NSLocalizedString("signin.button", value:"Sign in", comment:"Button to log in user"))

Let's break that down:

  • "signin.button" — A unique key for this string. Use something descriptive. That helps you and the translator.
  • value: — This is the "default" text iOS will show in your development language (likely English), OR if there is no translation available in the user's language yet.
  • comment: — Text that will help the translator understand the context.

You'll need to do this for every string in your SwiftUI app that a user might see and that requires translation.

NSLocalizedString() works with formatted strings or variables as well.

	  var fruits = ["Apple", "Banana", "Papaya", "Mango"]
	  Text(String(format: NSLocalizedString("fruit.count", value: "%d Fruits", comment: "Headline, number of fruits"),

Note that you need to use a variable substitution like %@ or %d in the localized string.

Pro tip
Always include a unique key and a helpful comment for the translators. Since you will need to add the NSLocalizedString call to every string a user sees, take an extra moment to tell the translators what this string is for. Remember, they'll be seeing it totally out of context, and your helpful hint is all they have! Knowing that a text is a title or a button, a noun or a verb, can be very helpful. Also make sure your key is absolutely unique. That will ensure that you can translate a string like "Clear" as both a button to remove text, AND as an adjective describing a transparent color. In other languages, these two words are certain to be different!

Method 2: Using Localizable.strings for SwiftUI Localization

An equally valid method to localizing a SwiftUI app is by manually creating a Localizable.strings file.

  1. Create Localizable.strings

    In Xcode, choose from the File -> New -> File… and select a Strings file. There are two critical points here:

    Name this file Localizable.strings — Xcode specifically looks for this name!

    Make sure to save this file at the Project level, not in a subfolder.

  2. Use LocalizedStringKey()

    Wrap your user-facing texts with LocalizedStringKey()


  3. Saving a Localizable.strings file in Xcode
  4. Add English text

    Open your Localizable.strings file, then add the key and English string:

    "signin.button" = "Sign in";
    Left side
    This is the key you used in your SwiftUI code. It should be unique.
    Right side
    This is the English text to display. Your translator will translate this text.

    Note the formatting with straight quotes "", an equal sign = and a semicolon ; at the end. All are required!

  5. Don't forget comments

    You can add an optional /* comment */ on the preceding line, which will help the translators:

    /* Button to log in user */
    "signin.button" = "Sign in";

    It even works with interpolated strings like .navigationBarTitle(LocalizedStringKey("\(’s Page"))) but make sure to use variable substitution in the strings file:

    /* %@ is the user's first name */
    "%@’s Page" = "%@’s Page";

    If you're unsure what to use for variable substitution, type it into the debugger:

    po LocalizedStringKey("My number: \(8.2)")

Exporting localizations into XLIFF in Xcode

In Xcode, Apple has embraced the XLIFF format for handing off to your translation team

Xcode has a very useful import & export feature for localization. Now that you've wrapped all of your texts in NSLocalizedString or LocalizedStringKey, it's easy to export it into a file format your translators can use.

(XLIFF is a standard XML-format supported by most translation software, including ours.)

Using Xliff with Xcode for SwiftUI localization

Importing and exporting localizations with XLIFF

  1. Export For Localization

    Select your project from the File navigator. Then choose the menu item Editor > Export For Localization….

  2. Save the Development Language

    In the Save window that appears, select where to save the export. Generally speaking, as translators, we only need the Development language, which is usually English. But if you have existing translations to share, you will also want to send those. You can export any language from the list of available ones for your project.

    And, there you have it! Your app will soon be multilingual. You have all the files you need to send to your iOS/Mac localization team!

  3. Export localizations development language xcode apple ios

    New since Xcode 10: Xcode will now export even more stuff in a folder it called an Xcode catalog, or .xcloc. In addition to the xliff file, it also exports some Source context (storyboards) and creates a Notes folder where you can put some screenshots for your translators or other instructions.

    This is when your translators work…

  4. Import the translations

    Your translators should return to you one file for each language using the language code as its name. That is, for French you'll receive an fr.xliff file, for Chinese, you'll get back something like zh-Hans.xliff.

    Import the files back into Xcode using the menu command Editor > Import Localizations…. Xcode will display a window with the differences between your existing files and the ones your translators have sent you. Press the Import button to finish.

  5. Import localizations translations xcode apple ios

Previewing translations in SwiftUI

One of the benefits of SwiftUI is live previews. You can preview your translations as you code thanks to SwiftUI's environment variables.

	struct ContentView_Previews: PreviewProvider {
	static var previews: some View {
		    .environment(\.locale, .init(identifier: "en")) 

Now, by changing that identifier to "es" for Spanish or "zh" or Chinese, you can see your translators' work live in the Xcode simulator preview!

Sign in to our developer portal

Create a free account in our developer portal to help test out your localization, get free price estimates, and expert advice

See also:

Language Codes
Complete list of ISO-639 language codes to use for your iOS app. Use these to name your xx.lproj folders.
iOS Glossary
This page contains many common translations for iOS terms, including things like Settings, Tap, etc.

Pseudolocalization —  testing you've found every string

Once you've finished preparing your .strings file you're probably having doubts that you actually managed to find every hard-coded string in your app. What about those error messages or that plug-in you use? Well, there is a quick way to check. It's called pseudolocalization!

Pseudolocalize my files

Plus get free cost estimate

Essentially, you use a program to substitute all the English (source) phrases with a fake language. Load up this gibberish Localizable.strings file into Xcode and then run your app. Check every screen and make sure all the text appears as the pseudo-localized text rather than your original. If you can't spot any missing strings, you're good to go.

Tip: Pseudolocalization is also a great way to make sure you've left enough room in your GUI for other languages. A common rule of thumb is that non-English languages are 30% longer, so tiny buttons and titles may not fit when you localize. Pseudolocalization can help you spot those cramped spaces too!

Start translating your app right away using this free Multilingual iOS Term Glossary. It contains common translations for iOS terms, including things like Settings, Tap, etc. in a dozen languages.

Multilingual iOS applications are what we do

Tiny Tiger iOS game Tinder localized into 29 languages Shazam iOS Localization Living Earth Weather App Localization Sky Guide for iPhone and iPad

Talk to a real translator.

Interested in professional iOS localization from a team that cares about making apps awesome? Unlike automated or cloud translation services which will translate your "bold" text as brave and "Archive" as a noun without considering it might be a verb, Babble-on is a dedicated team of translators that put as much care into localization as you do into app development.

You can talk to us about your project the whole way through, not just upload your strings and cross your fingers.

We'd love to help get your app ready for localization.

Contact us

For real.