Localizing macOS applications.
There are so many languages in the world (more than 6500). However, the majority of the population of Earth (~60–70%) is using only 50–60 of them. Good for us we don’t need to translate our applications to all 6500! In fact, not every application needs a localization, and it depends on the customer base (what language most of users speak) and how popular the application is. Additionally, localization may be considered as a feature that can encourage users to use the application, if they have problems understanding the content.
I was looking for a project to contribute to, and I found a project calld IINA.
IINA is a modern video player for macOS. It has many features that the native player (Quick Time) does not have, such as making playlists, adding subtitles, thumbnail previews and more. At the same time it has a beautiful user interface that is very similar to Quick Time. IINA is still in the process of development.
I opened an issue page, to find some bugs to work on, and I found that localization for many languages was requested. I did not have any experience in application localization and thought it would be a good opportunity to learn how to do it.
There are many tutorials on different websites on how to localize iOS/macOS applications. They are pretty straightforward and explain everything in details with step by step instructions.
Essentially, localization is done by moving strongly typed text (all text in
UIViews, etc.) to separate files. All the localized string are stored in files with
.string extension. The content is simple and consists of key-value pairs.
At the time I started, IINA was localized for many languages (still not completely for some languages). But if you are working on the project that does not have any localizations, you would start by adding a new language: There is a “Localization” section in the Info tab of the project navigator. New language can be added by simply clicking a
+ button. I recommend this tutorial if you are adding localization to a new project.
Since localization was already set up for this project, I decided to check Russian and Ukrainian localizations. To run the application using a particular localization (change the application language) you need to edit scheme in the xCode, or change a system language (which is honestly a bad idea).
Navigate to Product->Scheme->Edit scheme or click on the active scheme (top left corner next to
stop button) while holding
Here you can pick a language that will be a default language for the application when you run it with the xCode.
So I ran IINA in both languages and discovered that it was not fully localized in Ukrainian.
I started by filtering all files to only get
.string files for Ukrainian localization (for example uk.lproj/PrefGeneralViewController.strings or iina/uk.lproj/PrefCodecViewController.strings).
Those files were different from
Localize.string file, since they did not have a clear name for a key, but instead they contained
ObjectIDs of UI elements (such as “hWC-KJ-FuC.title”).
So adding missing translations in
Localize.string file was easy. Adding translations for other files was a little more difficult, since a few times I encounter missing
ObjectIDs, which meant that objects with those IDs wouldn’t be translated. To fix it, I opened localization files for same ViewControllers and copied missing
ObjectIDs from there. Now the only thing I needed to do was to translate them.
Once I finished with those I ran the application again and noticed that there was an entire menu tab that was still not translated. That was because I only added missing translations to
.string files that already existed. It was clear that the file with translations for that menu tab did not exists.
To add a localization file for that view, I opened a
xib file for PrefUtilsViewController and selected a checkbox for missing language in the Inspector menu.
(Note: I don’t remember why, but even after adding the file, translations did not work when I ran the project until I removed a reference (still keeping
.string file) and added it again).
The created file was empty, so I grabbed all the
ObjectIDs from one of the localization files for this ViewController. Now it was not difficult to add translations for those elements.
Here is a full list of all files that were changed or created.
There are a few things that should be taken into consideration when adding translations:
- Try to run project regularly to make sure all labels, buttons and drop downs are translated.
- Check as many views as possible (settings, menus, etc.)
- Check spelling when you add translations! (it is so easy and quick with online vocabularies).