|
iOS/macOS Localization and Internationalization |
iOS and macOS are two closely related operating systems from Apple. iOS (Wikipedia) is a very popular mobile operating system used in iPhones and iPads. macOS (Wikipedia) is a popular operating system used in Macs. Xcode (Wikipedia) is a software development tool used to create application for both iOS and macOS. 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/macOS. The following chapters describe iOS/macOS 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.
The end of the document contains links to get the full source code of the samples. After reading this document, we recommend reading a tutorial about how to use Soluling.
iOS/macOS applications are written using Xcode IDE and Swift or Objective C programming language. When you write an iOS/macOS application you add resource files into your Xcode project. Soluling can localize following resource types:
In addition to the 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.
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/macOS application file.
 |
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.
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.
 |
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.
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.
If you open it you can see its sub items.
Project.pbxproj is the actual Xcode project file that you select when you create a new Soluling project.
Now you can translate your project. After completed your project will look like this.
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 or order high quality translations.
The following table shows some pros and cons of each localization methods:
| Method | Pros | Cons |
|---|---|---|
| Resource file localization |
|
|
| Xcode project file localization |
|
|
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.
When you create a new Xcode project it will initially contain no localized languages.
Click + button on the Localizations frame to show a language popup menu. Choose German (or any other language you want to support).
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).
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.
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.
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.
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.
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.
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).
You only have to to this once if each file you add into your project.
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.
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
iOS and macOS 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.
<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\macOS contains following macOS samples:
All samples are written in Xcode 6 using Swift programming language. Soluling is compatible to Xcode 5 and Objective C too.
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.
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.
Copyright © 2010-2024 Soluling