|resources:||Home Mailing List|
Basic introduction to the use of AppleGlot and other Apple localization tools
Localizing a Cocoa application is not a difficult task, given the proper tools. It's easy to get the job done with Interface Builder and a little bit of patience. But, when you have to do recurrent translations of the same application, especially when this application is in an early development stage, it could become time consuming. This tutorial covers how to optimize efforts in localizing Camino, using tools mainly provided by Apple.
Download the tools
Everything starts at this URL:
which points to links to everything we need:
- an application used to extract strings from programs resources (AppleGlot)
- a text editor geared towards translation tasks, fit to handle UTF-8 strings (AD Viewer)
- a set of already localized strings which can ease the job and save some time
Of course, you have to install also Apple's Developer Tools (now called XCode Tools). You can find them usually with every major release of Mac OS X (10.1, 10.2, 10.3, ...), but the best way to have them is to download them for free from Apple's Developers site:
(you have to provide an Apple ID - you can register and get one for free - and the associated password in order to login)
You will use mainly just Interface Builder, from this collection of tools (and this tutorial is about not having to use it too much...), but the collection is loaded with interesting applications, scripts and documentation, so check those out.
The XCode Tools will be installed in the /Developer/ folder. The localization tools (AppleGlot and AD Viewer) can be installed wherever you want in your hard disk.
AppleGlot is an application that manages the localization process for an application. In order to do that, you have to create a "translation environment". The environment is just a collection of folders (under a main folder) each containing different elements; to create a new environment, once AppleGlot has launched, choose from the menu bar
and create a folder where you prefer.
Using AppleGlot, you will probably end up with several copies of Camino hanging around in your HD. This could be bad if you have set Camino as default browser, because you never know which of the copies (that are different versions and at different stages of localization) is going to be launched. A solution is to store your localization environment in a sparse disk image that you're going to mount only when you're translating Camino. See the Help for Disk Utility to learn how to build disk images.
Another way is to always rename the Camino.app as you put it into the AppleGlot environment: if you chose Camino.app as the default browser, Camino08.app or Camino09b.app won't launch as default browser.
Now, choose the target language
You can also set defaults for the language in AppleGlot's preferences: in the "General" tab, check "Automatically set the Base and Target Locales for a new project", then select your defaults. You will always be able to change these on per-project basis.
You might find out that your language is not supported, i.e. that it's not in the list of those available. Don't worry, we have a "plan-b"! Just select a random language, one you will never translate Camino into. Now, follow the rest of the instructions in this tutorial and, when you have finished your translation, copy your fresh, localized copy of Camino to your Desktop and run this application bundle. It is a script, which finds all occurrences of [your-fake-language].lproj folders inside the localized Camino and change them to [your-real-language].lproj folders. (Thanks to Jolita Šečkutė for providing this script and to Paul Borokhov for improving it!)
Instructions: This simple script assumes there's a localized version of Camino.app sitting on the Desktop, waiting for all of its [your-fake-language].lproj folders to be renamed to [your-real-language].lproj. Double-clicking on the script will launch it and provide you with a dialog box. Into the dialog, enter the name of the fake language, which you used in AppleGlot. Press enter, and a new dialog will pop up asking you for the real language, i.e. the language into which you have actually localized Camino. Press enter again, and sit back while the Finder renames all the folders accordingly. Upon successful completion, a dialog will pop up confirming the operations performed. Press OK in order to close the script and display a Finder window with the new ("patched") Camino selected.
To start working on Camino, use the Finder to copy the original application (not localized) into the folder _NewBase and put all the language specific dictionaries you downloaded (following links found at the URL given above, the Apple "Localization tools" page) into the folder _LanguageGlossaries (you also have to change the extension of the downloaded dictionary files from .ad to .lg).
Now you can go back to AppleGlot and open the environment previously created
Then, check the box that appears on the same line as the Camino.app icon in the window that comes up
Next, execute the following command (via the menu bar)
This will extract all the strings needed for translation and will create other objects in the translation environment. Among them, are the working glossary (Camino.app.wg) and the application dictionary (Camino.app.ad).
If you double-click on Camino.app.wg from the AppleGlot window, you can easily start doing the main localization task. If you have installed AD Viewer, it will be your guide in the operations, with some interesting features, the first of which is support for UTF-8 by default.
In addition, a compact and efficient "3-pane" interface shows the contents of the files to be modified (sequenced in the upper part), as well as their paths and single file names.
Moreover, there is a smart option (tag protection, which is turned on by default) which prevents you from writing to parts of the files that are not fit to carry translated content.
As you'll see, the Camino.app.wg file (which will be later consolidated into the Camino.app.ad file) is in fact an XML file containing strings to be translated and empty tags where to put translations to the chosen language.
Sample snippet of working file:
<base loc="en" >Proxy Settings</base>
<tran loc="it" origin="OldLoc exact match">[Your translation of Proxy Settings]</tran>
Given the tag protection feature, you will only be able to enter text where you ought to: in between the <tran></tran> tags.
A pleasant surprise, starting the work on Camino, was the one involving the pre-made downloaded dictionaries: thanks to them, about 200 strings out of 800 were already translated. But there's more about AppleGlot's dictionaries: you can also pick up the translation when someone quits doing it, because also the Camino application-specific dictionary can be shared and imported from another environment. The operation is as easy as dragging an existing Camino.app.ad file to the _ApplicationDictionaries folder inside the AppleGlot environment.
Another good point is the automated translation of special characters like quotes to equivalent SGML entities. A special word is needed for " entities, that points to double quotes: please note that in the original version of the strings containing " the entity is escaped, i.e. it has a backslash before (ex. \"). If you find an escaped entity, you have to keep that escape sequence, otherwise, the translation may not work, messing up other strings. A rule of thumb is to paste the original string between the <tran></tran> tags when special characters are needed.
Once you have carried on a part of the translation, you can suspend your work and save it for another occasion by calling, from the AppleGlot menu bar
This will update the environment and will create or update the target application (i.e. the localized version) which can be found in the folder _NewLoc inside the translation environment.
Once translation has finished you can call
in order to erase all non necessary working files and build the definitive localized package. The best part is that next time Camino will be updated, AppleGlot will take care of analyzing the old and new application and will ask you to translate only newly added or modified strings.
Of course, since AppleGlot works only on strings and builds localized interface files (.nib) based on the original language interface layout, you will have to manually check the .nib files and make some adjustments by hand, especially when you have localized strings longer than the original ones. Mostly, these adaptations take place in the preference panes interface.
Don't forget that Camino is a complex application: there are several different places where .nib files are stored. Also, don't forget that the Camino package contains the Talkback application (used to collect crash feedback data).
The .nib files are stored inside the Camino. app package. When you have finished working with AppleGlot, go to the _NewLoc folder of your localization environment and right-click on the Camino icon. Choose Show package content from the contextual menu and you'll get another finder window. Now browse folders until you find "Resources" folders and, inside of them, the [code].lproj folder (where [code] is the name or the code of your language).
Working with Interface Builder for this kind of task is very easy and straightforward. Open a .nib file with a double-click. Interface Builder will launch and you will see the main window for that file, containing different kinds of objects. Double-click the objects and you will learn that only some of them contain the actual graphical interface; once they are opened, you will be faced a view that resembles what you see in the actual application, but you can't interact with the opened window or perform any actions other than you can here modify the structure of the interface.
What you have to look for in this phase are strings that don't fit the space assigned to them in the interface canvas. This is quite usual translating from english, because English often uses short words and phrases. If you find a truncated string, click on it and you'll get a box surrounding the string. Use the box "handles" to enlarge it or to move it, if necessary. It is beyond the scope of this document to go deep in problems that may arise using Interface Builder. If you are having such problems, feel free to ask questions in the caminol10n mailing list.
One of AppleGlot's wonders is that everytime you update the localization, it compares the old translated application with the new "base"; so, if you adjusted the .nib files last time, you won't need to do that again (at least if the adjusted strings haven't changed).
Updating the translations
OK, now you have fully translated the latest Camino and... oh a new version is out... good, on the one hand, but it's more work for you. It used to be like that in the days before AppleGlot (actually before we knew it exists...). Now updating a translation can be a matter of minutes (depending on how much of the interface has changed). Here's a little list of things to do.
- Go with the Finder to the folders of your AppleGlot Camino environment
- Move the Camino.app located in folder _NewBase to folder _OldBase (overwrite old one)
- Move the Camino.app located in folder _NewLoc to folder _OldLoc (overwrite old one)
- Copy your freshly downloaded brand new build of (unlocalized) Camino.app to folder _NewBase
- Open your Camino environment with AppleGlot
- Run the Initial pass from the Actions menu
- When Initial pass has finished, open the Camino.app.wg file with AD Viewer and find out which strings you have to translate; you will only have to translate the updated or added strings
- Go on translating and following the usual AppleGlot procedure, with Incremental and Final pass
When final pass is done, you can check if there are adjustment to do in the .nib files. You'll be able to save some more time if you keep record, while you fill up Camino.app.wg, of the files that needed new translated strings; this way, you can open only the .nib files that were affected by the update.
Don't forget that your previous adjustments will be kept in following updates. After a few translation routines, you'll be able to quickly recognize if you have to fix .nib files and to rapidly find where to fix things.