Localization Instructions (Bean 3.x)
Please do not localize Bean without contacting me first to make sure that you are not duplicating someone else's efforts.
Bean 3.x uses GTMUILocalizer, courtesy of Google. This allows all translated strings to be loaded from .strings files. No direct editing of .xib or.nib files is required, since labels/controls/sheets are resized automatically. You should only have to edit two .strings files, and (somewhat optionally) three rich text help files. If you are trying to use software that edits the nibs/xibs directly, then you are doing it wrong.
To localize Bean, you will need the following:
• a plain text editor (preferably one that does syntax highlighting)
• a rich text editor for .rtf/.rtfd documents (such as Bean)
• the latest version of Bean.app
Select Bean.app in the Finder and make a compressed copy, in case you need a backup (File > Compress). Then right-click/control-click on the Bean.app icon and select 'Show Package Contents' from the context menu. Switch to column view (View > As Columns) and click on the Contents folder, then click on the Resources folder inside the Contents folder. Find the English.lproj folder inside Resources and control-drag it (which will copy it) to some other folder where you'll store your work. Note that if you drag instead of control-drag, you'll just get an alias to the English.lproj folder, and this is not what you want.
Rename the new copy of the English.lproj folder to match the target language (for example, ‘French.lproj’). To find the official name/abbreviation of the target language (it is often not obvious), consult the Resources folder of some other application which already contains a localization folder for the target language. Once the .lproj folder is properly renamed, edit the specific files inside of it that are listed below. Eventually, this whole folder will be copied back into the Bean.app bundle, inside the Resources folder, where the English.lproj folder also resides. If you don't translate the help files, just delete them. The English versions will be used instead.
Specific files to localize
This is the big one, containing all the translated strings for the app and for all the .xib (user interface) files. The file itself is a Unicode UTF-16 file and must be edited in a text editor. While you can edit this file in Bean, I would recommend editing it in a dedicated text editor that does syntax highlighting (like TextWrangler or Smultron). The most common cause of a localization not working is an omitted semicolon or quotation mark, that is, those marks that allow the app to parse the localization file and use it. Syntax highlighting can indicate when a quotation mark is missing.
The information in Localizable.strings follows a certain format. First there is a comment line that is meant to aid the translator, with the comment sandwiched between '/*' and '*/'. Then, information in the form:
"Key to be replaced"="Translated string";
Note that the 'key to be replaced' is not necessarily the string to be translated, but just a stand-in for it (you may have to read the comment line above it to know what or how to translate). Also note that if anything is missing, like the trailing semicolon, everything translated below that line will not work. This is the number one troubleshooting tip for localizations that don't work: look for the missing semicolon! Also, you never edit the key (the first member of the pair), only the second member. In the following example, 'Quit' is translated to 'Quitter' for a French localization. Only the word in bold below has been altered by the translator.
/* Quit (that is, Quit the app) */
Edit this file similarly to Localizable.strings. For each entry, edit the second string in quotes, that is, the one after the equal sign. Do not translate the name of the app; it should remain Bean. Note that the translations of the names of the file formats found in this file must EXACTLY MATCH the translations of the same keys found at the beginning of the Localizable.strings file, or else things will go haywire. You can just copy and paste them from that file to this one.
This is the help file for Bean.app, and contains a lot of information. You can open it in Bean and translate it directly, saving it as you go. Before you edit it, turn off File > Prevent Editing. Set to Prevent Editing again before you save it. If I make any changes or additions to this file, I will note it in the release notes so you can make the changes in your version. Note that some of the text (the table of contents and section headers) contain non-standard hyperlinks that allow the user to jump around the help file by clicking on things. Hyperlinked text will appear blue and underlined to denote the hyperlink. If you select this text, then start typing, the hyperlink will remain in the new text. You can add such a hyperlink in Bean using Format > Link… then adding a URL of the form bean://some_link_here. In Lion's Text Edit, command-k will show the link sheet. Each such link just finds the next matching link when clicked. When the file is opened in Bean as a help (documentation) file, the underlining will be gone, but the words will still be clickable. Note: it can be easier to select hyperlink-containing text using the arrow keys rather than the mouse.
Edit this file as a rich text file, similar to Bean_Help.rtfd above. Note that in the body of the document, the 'Bean version number: 3.x.x' should be changed with each release of the app.
Edit this file as a rich text file, similar to Bean_Help.rtfd above. Note that the version number toward the top of the document ('Version 3.x.x') should be changed with each release of the app. This file should also have Prevent Editing turned on before saving it.
Testing your localization folder
Make sure Bean.app is not running. Right-click/control-click on Bean.app in the Finder and select 'Show Package Contents' from the context menu. Switch to column view (View > As Columns) and click on the Contents folder, then click on the Resources folder inside the Contents folder. Copy the target_language.lproj folder into the app's Resources folder. The English.lproj folder should be there in the Resources folder as well.
Start up System Preferences, go to the Language tab, and drag the target language to the top of the list. (Click 'Edit List…' if the language list doesn't contain the target language.) Bean should start with the localization. Check every menu item and control for 1) correct localization and 2) correct placement/spacing. Notify me if there is a problem that needs fixing in the .xib files (like a label being cut off).
Thank you for localizing Bean!
jnrh2001 [at] yahoo [dot] com
Last updated: 2012 MAR 8 11:13