Document home

iOS

iOS/macOS Localization and Internationalization

iOS and OS X are two closely related operating systems from Apple. iOS (Wikipedia) is a very popular mobile operating system used in iPhones and iPads. OS X (Wikipedia) is a popular operating system used in Macs. Xcode (Wikipedia) is a software development tool used to create application for both iOS and OS X. Both operating systems share great number of API and the localization process for them is identical. They have very extensive support for different languages and locales. Soluling supports all kind of applications made for iOS/OS X. The following chapters describe iOS/OS X localization step by step.

Apple online documentation contains several useful topics:

Soluling can localize your complete Xcode projects (.pbxproj) or single resource files (.strings or .stringsdict). Read the process page to figure out what is the right method for you.

Localization process

iOS/macOS applications are written using Xcode IDE and Swift or Objective C programming language. When you write an iOS/OSX application you add resource files into your Xcode project. Soluling can localize following resource types:

In addition of above resources Xcode uses following user interface resources:

Soluling does not localize the above files because when using base internationalization Xcode uses only one set of user interface resources and extracts strings from those resources into a language depend directories (e.g. en.lproj and de.lproj). This is why when creating international software developers should always use base internationalization. All language specific data such as string are moved from the user interface resources to strings resources for more convenient localization. On runtime localized strings from strings resources are injected to the user interface resources. Read more about base internationalization from Apple's Internationalization and Localization Guide.

Once you have internationalized your Xcode project according to Internationalization and Localization Guide you can start localizing it. Apple's guide uses complex XLIFF localization. With Soluling you don't have to do it but Soluling can directly read all Xcode files. This makes localization much easier because instead of tedious XLIFF export import you just add your Xcode file into Soluling and it handles all automatically. So skip Localizing Your App chapter in Internationalization and Localization Guide and follow instructions given here.

Soluling lets you localize Xcode application in two ways. First is to localize string resource files. This is called resource file localization. Second is to localize the Xcode project. This is called project file localization.

Resource file localization

This localization method localizes the string resource files(s). String resource file is the most important resource type. It contains strings used by the application. The file extension is .strings and .stringdict (plural messages). There can be any number of strings resources in a single Xcode project. For example if you localize into German Soluling will create de.lproh\Main.strings. Finally when you rebuild your Xcode application the localized resource files get compiled along the original resulting a multilingual iOS/OS X application file.

Resource project If you want to use resource localization add a string resource file into Soluling project. Once Soluling has created the localized files recompile your application.

This method lets you to localize only strings resources. If you want to localize some other resources such as images or audio, you have to use the project file localization.

Project file localization

This method is similar to resource file localization but instead of selecting a single resource file (e.g. en.lproj\Main.strings) you select your Xcode project file (e.g. Sample\Sample.xcodeproj\project.pbxproj). Soluling scans all resources including strings, images, etc. When building Soluling creates localized versions of those resources.

Project project If you want to use project localization add an Android project file into Soluling project. Once Soluling has created the localized files recompile your application.

This methods has several advantages over resource file localization. First of all it allows you to localize other resource types but strings. Second it requires only one file to be added into the Soluling project file. If you later add new resource files into your Xcode project you do not have to add those files into your Soluling project file.

When you create a new Xcode project the root directory of your project contains two sub directories and one file, the project file.

Project file on macOS

The above image shows a root directory of a sample where Multilingual sub directory contains all the source code files of your project and Multilingual.xcodeproj file is the project file. Even on Mac the project file appears as a single file actually it is a directory that contains several files and sub directories. Soluling is a Windows application and you have to do the localization on Windows. Make you Mac drive visible on you Windows machine and go to the project directory. On Windows Multilingual.xcodeproj "file" appears as a directory.

Project file on PC

If you open it you can see its sub items.

Project file content on PC

Project.pbxproj is the actual Xcode project file that you select when you create a new Soluling project.

Initial project

Now you can translate your project. After completed your project will look like this.

Complete project

Now click Home | Build All ribbon button to create localized files. Soluling will create language specific folders (e.g. de.lproj) if not already exists and will write localized files into those folders. When you build your Xcode project after you created localized file use full build so Xcode will compile eveything (Project | Clean + Project | Build). This is sometimes needed because localized files files we writtend without Xcode knowing it.

If you don't have a Windows machine or you prefer to use only Mac you can use our cloud services. Go to Apple Store, install Soluling Xcode Utility and run it. The utility lets you select or drag-and-drop the Xcode project you want to localize. When selected the utility uploads the resource files (no source code files) into our cloud services where the services creates a project and lets you choose how to translate the project. You can enable web editing, order high quality translations, or send project to your translators.

Comparing methods

The following table shows some pros and cons of each localization methods:

Method Pros Cons
Resource file localization
  • Simple to use
  • Only strings resources can be localized
  • You need to add each resource file into your Soluling project or use wild cards (e.g. *.strings)
Xcode project file localization
  • Can localize all resources
  • You only need to select one file
  • You need the Xcode project file in addition of all resource files

In general if we recommend using the Xcode project localization unless you don't have full source code of the application when you have to use the resource file localization.

When Soluling creates localized resource files it writes them into the project directory under language specific folders (e.g. de.lproj for German). Soluling does not add the localization languages and localized files into the Xcode project file. You have to do that manually. You only have to do that once for each language and resource file. Once the language and the file are added and you use Soluling to update the localized files you do not have to do anything except compile the application and your multilingual application is ready to be uploaded to Apple Store.

Add localized languages into your Xcode project

When you create a new Xcode project it will initially contain no localized languages.

Initial project

Click + button on the Localizations frame to show a language popup menu. Choose German (or any other language you want to support).

Add German

Now Xcode shows a dialog where you can select what files are localized into German. Accept the default values where everything is selected and user interface resources use Localizable Strings (i.e. .strings files).

Add German continue

If you have already used Soluling to create German files the German target files already exist and Xcode show a warning.

Just ignore the message by clicking OK.

Repeat this for all languages you want to add into your project.

Localized project

Xcode will not overwrite localized media files such as image but will overwrite localized .strings files. This is why you have to let Soluling to create localized files again once you have added all localized languages. You use Xcode to write your code and user interface but from now on you don't have to import, export of modify localized files or settings in you Xcode any more. Every time you have modified your project use Soluling to rescan the project. If there are any changes such as new or modified strings, translate or let them translated and finally create localized files. Soluling will write the localized files into your project directory at their correct localization. All you have to do is to recompile your Xcode project every time Soluling has created new resources.

Add localized files into your Xcode project

If you add a new resource (e.g. Storyboard or Interface Builder files) you have to check the target languages. Select the new resource in the project tree and from right side panel locate Localization panel. It contains Localize button.

Localize

Click it to mark file localized. Xcode shows a message box where the file should be moved. Accept the default value (Base) and click Localize.

Localize base in XCode

Xcode shows the available target languages.

Check them all. When checking and the localized file already exists (e.g. Soluling has created it) Xcode will show following message box.

File already exists warning

Click Use file to use the existing file. If you click Replace file by mistake don't worry just let Soluling to create localized files again.

If you add a non user interface file such as image do not check the language matching your development language (English on most cases).

Localize language

You only have to to this once if each file you add into your project.

Existing translations

Sometimes you have an Xcode project this is fully or partially localized. No problem. When Soluling creates a new project it will automatically import all existing translations. Let's have an example. You have following Xcode project.

Multilingual project

As you can see the project has English as the development language and in addition the project contains German, Finnish, French, Japanese, Simplified Chinese and Traditional Chinese. When you create a new project Soluling detects those languages. Once you have created

Plurals in iOS/OS X

iOS and OS X have a plural enabled format function. Use Resources.getQuantityString function instead of Resources.getString whenever one parameter of the message is a numerical quantity. For example if you have someting like this

private void setMessageValue(int id, int count)
{
  TextView text = (TextView)findViewById(id);
  text.setText(res.getString(R.plurals.message, count));
}

change the above code to this

private void setMessageValue(int id, int count)
{
  TextView text = (TextView)findViewById(id);
  text.setText(res.getQuantityString(R.plurals.message, count, count));
} 

See <data-dir>\Samples\iOS\Plural and See <data-dir>\Samples\OSX\Plural samples.

Samples

<data-dir>\Samples\iOS contains following iOS samples:

Directory Description Notes
Driving A sample that shows how to localize an Android application. Try this first!
BiDi A sample that shows how to make a localize to bidirectional languages such as Arabic or Hebrew.  
Multilingual A sample that shows how to make a multilingual Android application.  
Plural A sample that shows how to use plural messages.  
Simple A simple sample  

<data-dir>\Samples\OSX contains following OS X samples:

All samples are written in Xcode 6 using Swift programming language. Soluling is compatible to Xcode 5 and Objective C too.

Configuring iOS/OS X Localization

 

Project localization

You create a Xcode project file localization project by adding a Xcode project file (e.g. D:\Sample\Sample.xcodeproj\Sample.pbxproj) into your Soluling project. You can configure how to localize your Xcode project file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.

Resource file localization

You create a resource file localization project by adding a Xcode resource file (e.g. D:\Sample\Sample\en.lproj\Main.strings) into your Soluling project. You can configure how to localize your Xcode resource file by selecting the item in the project tree, right-clicking, and choosing the Options menu. A source dialog appears that lets you edit the options. This source uses the following option sheets.