Localizing an application

Cocoa applications can easily be localized (i.e. translated) in as many different languages as you want. Apple's Developer Tools help you do this in a simple way.

Audience

This little article is targeted to people wanting to localize an existing application, without needing to modify the source code - it's all about resources. We suppose that the application itself has been written in such a way that, following Apple's guidelines, it can be easily localized, without needing to modify the code, or even having the code; it is just a matter of adding some new files to an existing working application.

Pre-requisite

You need to have installed Apple's Developer Tools, and the following shell script: TranslateNib.sh. This script, which will be invoked through the command-line (Terminal) has been written to ease use of nibtool/ibtool, an Apple's tool.

You also need to know a little bit how to launch a command through the Terminal, and how to modify a nib file using InterfaceBuilder.

What does need to be localized?

There are in general two kinds of files/resources which need to be localized:

• Strings files (files ending with extension .strings actually)
• Nib files (files ending with extension .nib)

For each language supported by the application, there is a folder named theLanguage.lproj inside the application wrapper, where theLanguage can be English, French, Japanese, etc.

Let's go!

Let's start with an example, GPGMail; OK, right, it's not an application, it's just a plug-in, but anyway it can be localized like any application. GPGMail has been developped in such a way that all the interface elements and all the messages can be translated in any language, without needing to modify GPGMail code.

First, let's make a backup copy of the GPGMail.mailbundle installed on your computer (in case something wrong happens ;-). Copy the file GPGMail.mailbundle (located in the Library/Mail/Bundles folder of your account) in a safe location, and we're going to work on the original installed plug-in. Select the plug-in in the Finder, right-click on it and choose Show Package Contents; a new window is opened, revealing the content of the wrapper. Navigate through the Contents then Resources folders, and you see a new folder named English.lproj. Inside this folder are located all files that need to be localized for GPGMail:

• GPG.strings
• GPGMailCompose.nib
• GPGMailPreferences.nib
• GPGMenu.nib
• GPGPassphrase.nib
• GPGProgressIndicatorController.nib
• InfoPlist.strings
• Localizable.strings

First we need to create the new folder inside which we will put the newly localized files. Let's start localizing GPGMail in French: we create a new folder, French.lproj, next to the English.lproj folder.

Localizing strings files

Open the .strings files using TextEdit located in English.lproj and translate the strings on the right of the = sign (do not modify the strings on the left!). The localized string should always be enclosed in double-quotes "" followed by a semi-colon ; , and if you need to put double-quotes inside the localized string, precede each one of these double-quotes by a backslash \:

For example, in file GPG.strings, you need to localized this:

    "Enter passphrase for %@:" = "Enter passphrase for %@:";

You modify the right part like this:

    "Enter passphrase for %@:" = "Entrez le mot de passe pour \"%@\":";

Note that the %@ (or any other %-escaped sequence) must be kept as-is: it will be replaced by another word/number/etc. defined during run-time. If you need to modify the order of these %-escaped sequences, this can be done: see http://developer.apple.com/documentation/Cocoa/Conceptual/Internationalization/index.html. Note also that the localized string must fit in one line; if you need to add line breaks, use the \n character sequence (litterally). Don't forget also to keep your line ending with a semi-colon ; as it was before you modified it!

Once you're done with translation, save the files using Unicode encoding (by using Save As... menu, you get a popup button in which you can choose the Plain Text Encoding), in the new language folder (French.lproj in our case), and verify that you didn't break file's format using the following Terminal command:

If there is no error message, file's format is correct :-)

Note that you don't need to type the path in the Terminal: just type the beginning of the command (up to the <), drag and drop the file from the Finder to the Terminal window, and the path is written down in the Terminal! Then type the end of the command (from the >).

Localizing nib files

To help you translate nib files, I wrote the TranslateNib.sh shell script; download and copy it in bin folder of your home directory, and make it an executable: in the Terminal, type:

Invoke the script in the Terminal with 3 arguments: the first argument is the operation name, either start or end, the second is the language name (e.g. French) and the last one the path to the original (e.g. English) nib file. For example, type:

This call puts strings to be translated from the nib file in a temporary .strings file, opens it with TextEdit to allow you to translate them, and also launches InterfaceBuilder to let you see the original nib file (do not modify this one!).

Now you need to translate the .strings file and save it (it is already in the right location). Then you invoke again the script with the same arguments, except that the operation name is now end. In our example, we type:

In the case of GPGMail, there are strings which are enclosed in double brackets <<>>. Don't translate these strings, they will be replaced by strings coming from some .strings file.

This call copies the original nib (if it doesn't exist yet) in a language folder (French.lproj), replaces the strings with the ones you translated, and opens the new nib file within InterfaceBuilder to let you eventually resize some elements. Note that the format of the translated .strings file is automatically checked here.

The script allows you to update an existing translation; you don't need to delete an existing one before re-creating it.

Known bug: With Xcode < 3.0, Apple's nibtool application, which is used by TranslateNib script, has a bug, reported to Apple: when updating an existing localized version with TranslateNib, all localized tooltips are lost and replaced by unlocalized ones. To get the list of original localized tooltips, you should do that before you invoke TranslateNib:

Then invoke TranslateNib normally and copy the old localized tooltips.

Testing the new localization

Once you translated all files, check in System Preferences that your preferred language is the one you want to test, then relaunch the application (e.g. Mail): now all strings and interface elements added by GPGMail should appear localized in the new language!

When everything works fine, you can send the localized files to the application author :-)

Feedback and questions

If you have any question on this little article, or notice some errors, please send a mail to gpgmail@sente.ch.

Software Library

More Mac OS X, WebObjects or OPENSTEP software to download from Sen:te