If you are willing to translate Pineapple News into some language other than English, I will pay you for your time in the form of a paid registration. I should warn you, though, that it will be a lot of work. You will have to translate all the documentation, the menus, the program’s windows, the strings file, and a few other miscellaneous things.
It’s best if you perform the translation steps in the order they are presented here, unless you have a good reason not to. It makes sense to translate the program’s documentation last, because it refers to buttons, menu items, and strings that you will will have translated earlier, so the proper text to use will be fresh in your mind.
Please do not undertake a translation without contacting me first. Someone else may already be working on the language you’ve chosen.
The ability to read and write English fluently, as well as your chosen second language.
A text editor capable of editing files in the UTF-8 character set. TextEdit, the editor that comes with Mac OS X, will work fine.
Interface Builder. You will need it for editing the strings stored in windows and menus. It is part of the Mac OS X developer tools, which you can download for free from Apple’s website, here.
Around ten hours’ worth of free time. There is a lot of text to translate.
It would be nice if you could make yourself available to refresh your translation from time to time. The program will inevitably gain new features and new documentation, so its translations will have to be kept up-to-date. This isn’t strictly necessary, though. I may well find someone who is willing to take over your translation if you find yourself unable to keep up with it.
For the purposes of this translation, it is important that your text editor can read and write UTF-8 text files. If you’re using TextEdit, it will usually do the wrong thing by default. To ensure that it will always use UTF-8, open its preferences window and look for the pane labeled “Default Plain Text Encoding.” It contains two pop-up menus for opening and saving files. Both should be set to “Unicode (UTF-8).” If you are using some other editor, you’re on your own, but it’s still important for it to be configured to use UTF-8.
Your translated documentation should use “curly quotes,” rather than ugly straight-up-and-down quotes, because it’s more typographically correct. There is a free Mac OS X services menu add-on that makes it easy to add curly quotes to text, called WordService, from Devon Technologies. You can download it here. Once you have installed WordService, you can select a range of text and press ⌘-shift-" to apply curly quotes. However, it is unwise to apply curly quotes to an entire document at once, because some quote marks in HTML documents must be maintained as the ugly straight-up-and-down kind. A HREF tags, for example, must use straight quotes to delimit URLs.
Now you must grovel around inside the Pineapple News application bundle. In case you didn’t know, most Mac OS X applications are “bundled” apps, which means that they are actually folders that contain the application’s binary executable and all of its support files. Use the Finder to navigate to the folder where Pineapple News is stored. Control-click on the app to display its context menu, and select “Show Package Contents.” A new Finder window should appear, displaying the application’s guts.
Navigate to the application’s Contents/Resources subdirectory. In that subdir you will find another one called English.lproj. You must make a copy of the folder alongside the original, which has the name of your chosen language. For example, if you are translating to German, you would copy English.lproj to German.lproj. You might be thinking: shouldn’t the new folder be called Deutsch.lproj? That’s the way I would have done it, but Apple chose to name resource directories according to the languages’ names in English. You have to follow suit, or your translation won’t work.
Have a look inside your new LanguageName.lproj folder to see all the files involved. Every single one of them will have to be translated. If that thought isn’t too daunting for you, read on.
Exit Pineapple News, if it’s running. Open the Mac OS X System Preferences application. Choose the pref pane labeled “International.” The first tab shows your preferred language list. Drag your chosen language to the top of the list, so that it will be used in preference to all others. Exit System Preferences, to ensure that your settings are saved.
Now start up Pineapple News. It should run as normal, but it will still be in English, because you haven’t translated anything yet. As you get each new element translated, it should be reflected onscreen. Now exit the program, because it should not be running as you complete the steps below.
The program’s strings live in a file named strings.txt. It’s a plain-text file in the UTF-8 character set. It contains several hundred entries, in this form:
LanguageEntryName "Entry contents goes here" ; Comment
A language entry’s name and contents must both be on a single line. The entry’s contents must be delimited with straight quotes. Comments begin with a semicolon, and extend to the end of a line.
Some related entries are synonyms for a single concept:
BoolNo1 "Off"
BoolNo2 "No"
BoolNo3 "False"
BoolNo4 "Disabled"
More than one is needed because this set of strings may be used to parse input from unknown sources, such as text typed by the user or input from a text file. The first one is the most important, as it will be used when the program outputs text for the user to see. If you can’t think of four terms that mean “no” in your language, it’s acceptable to repeat a word two or more times.
A few language entries contain the entire text for an alert sheet or dialog:
AlertName "Alert Title\tAdditional text\n\nName: %1"
The \t (a tab character) signals the end of the alert’s title, and the beginning of its secondary text. Newlines are represented with \n characters.
Some language entries contain placeholders for variable text that will be filled in at runtime.
FunnyHouse "Total days: %1 Total weeks: %2"
When translating entries such as this, it’s acceptable to rearrange the placeholders so that %2 comes before %1, if that makes sense for your chosen language’s grammar.
You will sometimes encounter constructions like this:
ByteSizeBytes "%1 %1p?byte:bytes"
This is so that different text can be used for numbers that may be singular or plural. The text after the question mark and before the colon will be used if this string is printed with a singular number. The text after the colon will be used if the number is plural.
At runtime, %1 will be replaced with a number. For the sake of discussion, let’s say it’s 22. That number is plural, so the string would be printed as “22 bytes”. Now let’s say that string is printed again later on, with the value 1. That number is singular, so it would be printed as “1 byte”.
Most entries are hopefully self-explanatory, but a few tricky ones will be covered individually.
LanguageName This should be set to the name of the language you are translating, as it is known in that language. For example, if you are translating to German, the value of this string should be "Deutsch".
Singular This entry lists integers that should be considered singular. The default text for this entry is "-1 1". In English, the only singular number is one, but many years ago, I discovered that Portuguese considers zero to be singular as well.
DateTimeFormat This string will be used to format date/time values for display to the user. Here’s the default English version:
DateTimeFormat "%n3 %d1 %y1 %h1:%m1%a1"
It results in a string that looks like this: Oct 16 2005 05:57AM
Here’s a list of all the variables that can appear in the string, along with their meanings.
%a1 AM/PM, long uppercase %a2 AM/PM, long lowercase %a3 AM/PM, short uppercase %a4 AM/PM, long lowercase %c1 Century, two digits %d1 Day of month, two digits (leading zero may be added) %d2 Day of month, one or two digits (no leading zero) %f1 Fractional second, one digit %f2 Fractional second, two digits %f3 Fractional second, three digits %f4 Fractional second, four digits %f5 Fractional second, five digits %f6 Fractional second, six digits %h1 Hour (1 - 12), two digits %h2 Hour (1 - 12), one or two digits %h3 Hour (0 - 23), two digits %h4 Hour (0 - 23), one or two digits %m1 Minute, two digits %m2 Minute, one or two digits %n1 Numerical month, two digits %n2 Numerical month, one or two digits %n3 Alphabetic month, short %n4 Alphabetic month, long %s1 Second, two digits %s2 Second, one or two digits %t1 Timezone bias %w1 Weekday, short %w2 Weekday, long %y1 Year, four digits with century %y2 Year, two digits without century
The final step in translation the program’s strings involves the file named InfoPlist.strings. It contains a small subset of the strings found in strings.txt in a format used by Mac OS X itself, so that the Finder can display the program’s name and summary information in your chosen language. Since this file contains exact copies of strings found in the main strings file, I gave the program the ability to generate this file automatically. All you have to do is put the current copy of InfoPlist.strings into the trash and start up Pineapple News, and it will generate a new copy of that file that matches the main strings file.
To complete this step, you must have Interface Builder installed. In your LanguageName.lproj folder, you should see a file named MainMenu.nib. Double-click on it, which should open the file in Interface Builder. If it doesn’t open, then you haven’t installed the developer tools properly.
A small Interface Builder window will show you all the resources stored in the NIB file. Double-click on the resource named “MainMenu,” if it is not already displayed. Now you must translate the text of all menu items from English into your chosen language.
Macintosh users place a high premium on predictable apps that follow Apple’s Human Interface Guidelines. For that reason, wherever possible, you should use the same text as found in other apps that have been translated into your chosen language. For example, almost all the items on the Edit menu are the same as on any other program’s Edit menu, so you should be able to copy the proper text from some other app. Don’t deviate just to be different.
Be careful when editing NIB files! They contain information on how menu items and other controls connect to code inside the program, which you should not modify. Changing NIB connections can subtly break the app in a way that will be difficult to detect.
When you’ve finished editing the menu’s text, save it to disk by pressing ⌘S. Now start Pineapple News. Its menus should display the text you just translated in your chosen language. Exit the program before continuing the translation.
Every NIB file in the LanguageName.lproj folder you copied contains one window that must be translated (except for MainMenu.nib, covered in the previous section). Double-click on each NIB to open it in Interface Builder, which should display a small window showing all the resources contained in the file. There will be several resources, but you only need to concern yourself with the NIB file’s sole window, which is represented by an icon that looks like a tiny window. Double-click on it to display the window resource onscreen.
A NIB file is very complex. It contains a great deal of information about how a window will interact with its host program. If you change any of the connections in the NIB file, you may introduce subtle bugs that will be hard to find later on. Be sure to change nothing in the program’s NIB files but the strings.
Translate all the English strings into your chosen language. You may find that you need to increase the size of some controls so that your translated strings will fit. If larger controls means that you also have to increase the size of the window, then it gets a little trickier. In that case, you will also have to change the minimum and maximum size of the window, which is used to enforce how small or large the user can make the window by dragging its resize corner. You can edit the window’s size constraints by pressing ⌘-shift-I to display Interface Builder’s “Show Info” window.
Make sure that you don’t miss any strings that need to be translated. For example, some windows have pop-up menu buttons that contain a menu full of pre-built menu items that need to be translated. If a pop-up menu button contains a menu with only one item that has a nondescript value such as “<Empty>,” then you can assume that its menu items will be filled in at runtime, so you don’t have to translate it.
Some windows contain tables and outline views. The tables’ column header names in English can be seen in the NIB files. You don’t have to translate them, because the column header names are also found in the strings.txt strings file. Column header names from the strings file will be loaded into the windows’ tables at runtime, overwriting the English equivalents found in the NIB files.
A few of the programs’ NIB files are outside any .lproj directory. You don’t have to worry about them, they contain windows that do not need to be translated. A few contain strings in English, but they will be overwritten by the localized equivalent strings from strings.txt at runtime.
When finished editing the strings in a NIB file, press ⌘S to save your changes to disk, then go on to the next one.
If you have completed all the steps before this one, then you’ve done enough of the work to convince me that you’re serious. Contact me and let me see your work, and I’ll give you your registration key. It will come in handy as you are performing this step, which is the hardest of all.
Inside your LanguageName.lproj folder, you will find another folder named Help. That’s where all the documentation files live. They are plain old HTML text files in the UTF-8 character set. Open them all in turn in a text editor or your favorite HTML editor and translate them. The only help topic that does not need to be translated is the one you are reading now, which explains how to perform translations. Any translator will need to be proficient in English, so it’s a moot point.
The manual’s title page is in the file Help.html. Give yourself credit in that file, right below the existing authors’ names. For example, “Translated into Swahili by Tori Anderson” would be appropriate.
There is one additional HTML file to be translated that lives outside the Help folder. It is Credits.html. It contains text that is used to populate the program’s About window. Translate the contents, and give yourself credit here as well, using the same wording you used in Help.html.
You must not change the names of the HTML files. For example, do not rename main_window.html to my_languages_word_for_main_window.html. The program sometimes refers to individual help files by their filenames, so they must not be renamed.
The help folder contains a file called Help idx. It’s created by the Apple Help Indexing Tool, and it enables fast indexed searches. You’ll need to install Apple’s developer tools for the translation, so you’ll presumably have the help indexer installed on your system. You can use it to update the help index, once you’re finished translating the docs. All you have to do is drag the help folder onto the help index tool, and it does the rest. You don’t have to, though. I can do it for you, once you deliver the translated resources to me.
At this point, your translation should be complete. Run the app and make sure that everything looks okay. Poke around in the menus, especially ones you don’t often use. In particular, select all the items on the Help menu. Have a look at all your translated help topics inside the app itself, to make sure that they are being displayed properly. Open up the About window, and make sure its text is in your chosen language.
It’s a good idea to “road-test” your translation for a few days before declaring it complete. You may discover that some of your translated text doesn’t make sense in the context of the app. You may find something that is in English that shouldn’t be, which could well be a bug in the program that you should report, so I can fix it. Text that is written into the programs’ log files is always in English, so don’t report non-localized log text as a bug.
Once you’ve found and fixed any annoying details, you are ready to send me the results. Create a ZIP archive of your translated copy of the program and send it to me as an e-mail attachment.
If you’ve gotten this far, thank you very much for your help. I know this is a great deal of work to do for one measly paid registration, so you must have done it out of a fondness for the program and a desire to share it with others who speak your chosen language. Thanks so much for your contribution to the Macintosh ecosystem, which makes it a little bit better place for all of us.