Localization Instructions.rtf

Instructions for localizing Bean : a Word Processor for OS X

You will need :

· Bean.app (for the English.lproj folder and to test your translation)

· Interface Builder (to edit the .nib files)

· Xcode, Bean, or Text Edit (to edit .html files and UTF-16 format .strings files)

Locate Bean.app in the Finder. Make a copy of the app in case you run into problems. Right-click or control-click on the app icon and choose ‘Show Package Contents.’ Switch to column view in the Finder, click on the Contents folder, then click on the Resources folder. You will see the ‘English.lproj’ folder inside Resources. Duplicate this folder and rename it for your language (for example, ‘French.lproj’). To learn what to name the folder for your language (it is not always obvious), consult the Resources folder of some other application which already contains a translation for your language.

You are ready to begin localizing the four types of files that need translation work :

· .nib files (user interface files)

· .strings files (containing text strings)

· .html help files

· the Credits.rtf file

Localizing .nib files

Open the nib files in your language.lproj folder one at a time in Interface Builder (IB). IB is an application used to graphically design interface objects using controls and labels. You install it from the OS X installation disk.

Note that one nib file can contain several windows and sheets. Start with MarginSheet.nib since it contains only one sheet (called ‘Window’).

Translate all the text field labels and button labels. In general, changes to text don’t ‘take’ until you tab to the next field. You can resize and move the controls if you need to, as long as they retain the general layout of the original nib. I have tried to leave room for the controls to be resized by localizers (many languages need more space than English). Cmd-z (undo) is invaluable when doing this kind of work!

Don’t forget to save your changes before closing the nib file.

Apple says :

· Objects in a nib file typically have connections between them that should not be broken. You should lock all connections (an option in the Preferences > Editing panel of Interface Builder) before editing the nibs. If using IB 3.0 (Leopard), select the nib in question, then in the Identity panel of the Inspector set Lock to ‘Non-localizable Properties.’

· Panels and windows usually have minimum or maximum sizes that are specified through the inspector panel. If you must make a panel or window wider for a given language, it's likely that the minimum size also needs to be modified.

· Some UI objects support “tool tips” – little blurbs that come up when the user hovers on the UI element for a short while. You enter these strings in the inspector, where they should also be localized.

Notes:

You do need to localize all the tool tips, but you do not need to localize the accessibility tool tips.

Please remember to translate the tooltips in JHDocument.nib for the zoom slider and the page up and page down buttons (sometimes these are overlooked).

Be careful about moving panels and windows around. If you move the Inspector to the right on your screen, for instance, if might not even appear on the screen of someone with a smaller display.

Localizing .strings files

The files ending in .strings should each be opened in an editor capable of reading and saving UTF-16 format text files, such as Bean or Text Edit. These files are typically full of pairs of strings. Never touch the first member of each pair...it is the key that is matched up with a text string in the program code. The second member of each pair is the one to translate and to change.

Apple says :

· If a string contains multiple variable arguments, you can change the order of the arguments by using the “$” modifier plus the argument number

/* Message in alert panel when something fails */

"Oh %@! %@ failed!" = "%2$@ blah blah, %1$@ oh!";

· Just as in C, some characters must be prefixed with a backslash to be included in the string properly. These characters include double-quote, backslash, etc. You can specify carriage returns with “\n”:

"File \"%@\" cannot be opened" = " ... ";

"Type \"OK\" when done" = " ... ";

Notes:

It helps to edit .strings files in a text editor that color codes text according to its function, like XCode does. One missing quotation mark can cause all subsequent localization pairs to not work, and with automatic color-coding you can spot these problems easily.

A helpful application for comparing two files to determine any differences (to see if a file has changed between versions, for instance) is fileMerge.app. If you installed XCode, you should have fileMerge installed too.

For Help to work, the name of the Help Book in InfoPlist.strings

CFBundleHelpBookName = "Bean Help";

must match the content identifier found in the Help directory’s Index.html file:

Localizing .html files

Apple help files are .html files – just like those used on the web. You can use Text Edit or Bean (or any text editor, really) to edit the .html code files directly. Typically, you can ignore all the tags contained by angle brackets, as these are the hyperlinks and formating. Don’t translate the GNU GPL license legal text. Also, I don’t care if you translate the essay page called ‘About Bean...’ or not. If you are pressed for time, just translate everything but the Help files. I’ve tried to make Bean as intuitive to use as I could.

If you don’t want to work directly with .html code, which is understandable, you can open the .html help files in Safari, cmd-A to select all, Edit > Copy, Paste into a new Bean file, save the file as .rtfd, then File > Export > To .html and that .html file should work fine as the newly localized .html file. But just in case, proof it to be sure.

Credits.rtf

Please give yourself credit for the translation in this document (which supplies text to the ‘About Bean’ info box).

Testing the localization

When you are ready to test your translation, open System Preferences, click International, and drag the language in question to the top of the list. Start up Bean and check each item, including the About Box and Help. Also check the names of the file formats in the Save Panel.

Create a zip archive of the language.lproj bundle and mail it to jnrh2001 [at] yahoo [dot] com.

Updating the localization

So far, I have had horrible luck using tools that are supposed to allow for incremental updates of localized resources (so you don’t have to translate everything all over again for each version). When I use Apple’s ibtool, maybe 1 out of 15 items merge, which hardly makes it worth it. The merge fails even when the key for two items (the ID number) is the same. It looks like whenever the size or position of a control is changed, ibtool ignores it during the incremental update.

Other options

iLingual allows you to translate strings from resources easily, and unlike other localization software, it is intuitive. Plus, if you are working on freeware (like Bean) or are doing volunteer translation work, there is no license fee! You will still have to look at the resulting nibs are tweak them, however.

Thanks for contributing to the Bean project!

Revised 4 April 2008