Localization

Introduction

Bit Slicer can be localized, or translated, into different languages. This document explains how one may want to translate Bit Slicer into a language different than English.

Setting Up a Language

Bit Slicer 1.7.2 or later is required for making localizations. When in doubt, make sure the latest official version is installed.

1. Navigate to the 'Bit Slicer' application in Finder.
2. Duplicate the application; rename the copy to 'Bit Slicer (Localized)'
3. Right click (or control + single click) on localized named application, and choose 'Show Package Contents'
4. In the new Finder window, navigate to Contents -> Resources.
5. Duplicate the en folder and rename the copy to the language code you want to localize into (e.g: es is for Spanish)
6. That's it. Be cautious about updating the localized application to a newer version; that will overwrite the changes you'll make!

Translating

First, the language that is being localized must be set as the preferred and primary language in System Preferences - Language & Region.

A programming text editor will also needed. Please don't use TextEdit, which doesn't work well for editing plain text. Some candidates are TextMate 2, TextWrangler, and Sublime Text 3.

Every file in the localized folder we duplicated earlier will need to be translated. The majority of these files are strings files, and an entry in them may look like:

\* Prompt message that shows up in the save panel for choosing a folder to save memory dump files to */
"savePanelPromptMessage" = "Choose a folder name to save the memory dump files to.";

This example is taken from [Code] Dump All Memory.strings. The first line is a comment surrounded by /* ... */ explaining what the string (or text) on the next line is for. The next line is in the format:

"key" = "value";

We want to change the value to reflect the language that we want to translate to, and want to do is for all the strings in every string file here.

For instance, let's change the above key-value pair to:

\* Prompt message that shows up in the save panel for choosing a folder to save memory dump files to */
"savePanelPromptMessage" = "Blah Blah Blah";

Re-run the application, navigate to Memory -> Dump All Memory in the menu bar, and you will see the save panel now shows "Blah Blah Blah" at the top.

All the keys are in camelCase style, with the exception for the keys in the Localizable file. A couple of files (with .stringsdict extension) are also not strings files but XML files used for handling pluralization (more on that later).

Strings Structure

All files with the .strings file extension are actually called tables, each which contain many string definitions.

The name of a table corresponds to the functionality in the application. For instance, Search Document Window.strings corresponds to the search window in Bit Slicer.

Localizable is a generic table that doesn't fit anywhere else.

Tables that have [Code] in the filename are strings generated from source code. Tables that don't have [Code] are generated via a interface designing utility.

Every string in [Code] tables (and Localizable.strings) need to be translated but this is not necessarily the case for tables that don't have [Code] in their name.

Often the interface designing tool I use will generate strings that don't need to be translated. Such instances of values are:

• Text Cell
• OtherViews
• Box
• Ones named with a lowercase underscores convention such as nop_variable

One special table, however, is MainMenu.strings which contains strings for all menu items in the menu bar. Some of these strings may already be auto-translated when the application is launched despite what values are specified in the file. First run the application and see which strings in the menu bar aren't translated before providing translations.

Another special case is the file named InfoPlist.strings, which doesn't have its key surrounded in double quotes; this is what shows up in the applications About window.

Some last notes:

• Keys that have undo in them show up as undo/redo menu item in the File Menu after performing their action
• Keys that have Alert in them usually are paired with Title or Message, for an Alert dialog message
• Values that have … at the end are not three periods, but an ellipsis character. Don't type out three periods which doesn't look the same; copy and paste this character when translating.
• Keys that have Format in them have values which contain tokens that will be replaced when the application is running.
• Keys that have Notification in them refer to notifications sent to OS X when Bit Slicer is not active.
• Some keys and values refer to contextual (right click) menu items.

Pluralization

Some languages have different pluralization rules. For example, in English if we use the sentence:

Pet 3 cats

and if somebody evil takes away 2 cats, the sentence then turns into:

Pet 1 cat

As seen above, the sentence changes if we pet one cat, or any other number of cats. In English, we have two forms for all possible number of cats. If we were translating to a language like Arabic, as many as six different forms exist!

The handling these plural rules are described in .stringsdict files, which are in a slightly confusing XML format.

Looking at one example that desribes the label for how many values are being displayed from [Code] Search Document.stringsdict:

<key>displayingValuesLabelFormat</key>
<dict>
	<key>NSStringLocalizedFormatKey</key>
	<string>Displaying %#@values@</string>
	<key>values</key>
	<dict>
		<key>NSStringFormatSpecTypeKey</key>
		<string>NSStringPluralRuleType</string>
		<key>NSStringFormatValueTypeKey</key>
		<string>lu</string>
		<key>one</key>
		<string>_NUM_ value</string>
		<key>other</key>
		<string>_NUM_ values</string>
	</dict>
</dict>

The string format shown is "Displaying %#@values@" and we define values to output "_NUM_ value" if values is one, or "_NUM_ values" if the value is something other than one. Bit Slicer then substitutes _NUM_ for the actual number in numerical localized form (e.g, 1000 would be 1,000 in English).

This example just makes use of one and other since it's English. All possible values are: zero, one, two, few, many, and other with other being the only mandatory and fail-safe one. This should cover plural rules in all languages.

Unfortunately these pluraization .stringsdict files are not handled on OS X 10.8 (Mountain Lion), which Bit Slicer still supports. In this case, the strings in the corresponding .strings file needs to be changed.

For [Code] Search Document.strings for instance:

/* Display Value Label format for one variable; only used prior to 10.9 */
"displayingSingleValueLabelFormat" = "Displaying _NUM_ value";

/* Display Value Label format for multiple variables; only used prior to 10.9 */
"displayingMultipleValuesLabelFormat" = "Displaying _NUM_ values";

we handle two cases for when the value is one or something other than one. This is not ideal for other languages but it's still better than nothing for 10.8 users.

Finally, most of the time a XML .stringsdict file isn't needed for pluralization. For example, if we don't need to specify a number in the above pet example then we only have two forms for any given language:

Pet cats

Pet cat

Support

If any difficulties arise, please feel free to contact me, or create a public issue where we can have a discussion. Chances are I may have to alter the sizes of controls in Bit Slicer to have some text show up correctly.

When all is done and you want your localizations to show up in the next release, send me a copy of the files so that I can review them. If you are tech savvy, feel free to create a pull request of the changes on GitHub.