One of the exciting features present in SoundBridge software releases starting with version 2.3 is the ability for the SoundBridge to display its interface in multiple languages. In addition to the languages we ship with, it's possible for users to create their own translations if they would prefer a language that is not provided.
The following instructions explain how to do this.
Before you start
Please note that all SoundBridge models support characters in the standard Unicode Basic Latin (0000) and Latin-1 (0080) tables. VFD-equipped models (all models except M500) also support Cyrillic. Only the SoundBridge Radio (and SoundBridge M1001 units sold in the Asian market with a 32-pixel-high display) can run the user interface in Japanese or Chinese. Characters that are not available will be rendered with a "missing character glyph". If your language requires extensive use of characters not supported on your model, you may not want to spend the effort on localization, as they will not display properly.
Getting the Language Resource File
All of the SoundBridge user interface strings appear in a language resource file. This file can be downloaded from the SoundBridge to a computer, edited to add a localization, and then re-uploaded to the SoundBridge to allow it to use the new language.
The first step to localization is to get the resource file. The file can be retrieved from the SoundBridge itself, via the built-in web server. Connect to your SoundBridge's internal web server (see the User's Guide for instructions if you don't know how), and choose the "Configuration" page.
In the Configuration page, there is a Language section, and there is a link that says "View Current Language Resource File". You can either click this link and then save the page, or right-click (control-click on the Mac) the link to save the link to a file.
Later, after you have edited the file, you will come back to the Configuration web page and use the "Browse" button to select your edited file, then click Update to load the file to the SoundBridge. If no errors are detected, you will then be able to select your new language and test your changes. Otherwise, errors will be reported, and you should correct them and upload again.
Text Encoding is crucially important
This file is in the UTF-8 encoding in order to support accented and other special characters. Please be sure to edit the file in a UTF-8 compatible editor and save it out again in UTF-8 encoding. Notepad on Windows and TextEdit on the Macintosh both handle UTF-8 properly. You may need to force your editor to treat the file as UTF-8 if it doesn't recognize the encoding automatically. (Notepad has an "Encoding" option in its open/save dialogs, and TextEdit has options for this in the Preferences.)
You can ensure that your editor has opened the file correctly by looking at the Swedish localization of the SR_WELCOME_MESSAGE. If it says "LÃ¥t musiken spela" (note the circle over the a), then the encoding is correct. The currently-shipping resource file contains Japanese and Chinese localizations. If your system has suport for these languages installed, you should see the Japanese and Chinese characters. If not, you will probably see "????" for these strings.
The easiest way to preserve the file’s text encoding is to always edit the file and then choose “Save†rather than "Save As...". Most editors will use the original text encoding when choosing "Save", but may choose a different one with "Save As...". You may want to make a copy of the original for reference.
Line-ending formats
Different operating systems represent the end of a line differently. If you see all the strings jumbled together in the file, rather than neatly arranged as shown below, then most likely your editor is not correctly interpreting the line endings. We have tested this with both Notepad and TextEdit and found them to work properly. Consult your text editor's instructions for how to adjust the handling of system-dependent line endings.
Format of the file
The format of the file is a list of string names, each with a list of the localizations for that string. For example, two of the menu items from the server/settings menu appear as follows in the file:
- Code: Select all
SR_CZ_MENU_SETTINGS
eng "System Configuration"
fre "Configuration du Système"
swe "Systemkonfiguration"
ger "Systemeinstellungen"
spa "Configuración del sistema"
SR_CZ_PLAYLIB_PREFIX
eng "Play %s"
fre "Lire %s"
swe "Spela %s"
ger "%s wiedergeben"
spa "Reproducir %s"
When adding a language, the localizer should add the name of the language and a 3-letter identifier at the top of the file, in the SR_CURRENT_LANGUAGE list. If the languages is already shown there, but with a "#" at the beginning of the line, just remove that "#". The "#" character is a comment character in this file format -- lines starting with "#" are ignored.
Then, for each of these resource names, add the localized translation of that string, following the model of the other languages.
Localization rules
If you intend to share your localized file with others, it is very helpful to adhere to the following rules:
- Please leave “eng†as the first line of each text item.
- Please do not re-order any of the languages in each text item.
- When translating an item for the first time, please add your translation as the last item in the list. It’s not important that the list of languages be in the same order for each text item, but it’s easier to use text-merge tools to merge these changes if new additions come at the end of each item.
- If you are modifying/correcting the translation of an item, please leave it in the same location in the list.
- A few items have special formatting, described below. Please follow these formatting rules, and feel free to ask if there are questions
- Even if the localized string is exactly the same as the English string, please go ahead and add an entry for the language you're adding. This allows our automated merging tools to work better.
- Any string starting with “SR_WP†is displayed on the SoundBridge internal web page. You may see HTML-escaped characters in the English translations of these strings (for example, “Salt & Pepper†would appear as “Salt & Pepperâ€. Generally, any sequence starting with “&†and ending with “;†should be left unmodified unless the translation would contain a different character.
- Some strings may contain special sequences of characters preceded by the "%" character (see the "Play" item in the sample above). These are used at runtime to substitute text or numbers into what is displayed on screen. %s means that a string will be substituted. %lu means that an unsigned 32-bit number will be inserted, and %ld means that a signed 32-bit number will be inserted. These are standard C sprintf substitutions. Please do not modify these sequences, although you may need to move them depending upon the grammatical rules. See the other languages for examples. In the example above, SR_CZ_PLAYLIB_PREFIX is the menu option shown in the library list, and the %s will be replaced with the library name (for example: "Play Mike's Music Library"). Notice how the "%s" appears at the beginning in the German translation, but at the end in the other languages, because of differences in grammatical rules.
- Some strings contain a "$product" token. The SoundBridge will substitute the product name for this token when the string is displayed. (For example, "Reboot $product" will be displayed as "Reboot SoundBridge" or "Reboot SoundBridge Radio", depending upon the product.) Do not localize the word "product" -- leave it as-is.
- Many strings use a … character to indicate an operation in progress, or to indicate that clicking a menu item will require further interaction. This is a Unicode ellipsis character, not three separate periods. You can copy and paste from another string if you need to. Or, on the Mac, just type Option-; (semicolon).
- On some models, you may see short variants of strings, for example SR_IT_ACQUIRE_LICENSE_SHORT. These strings are used when the full-length version will not fit on screen, and so should be kept as short as the other localizations.
Items with special formatting:
Menus
The following items are the contents of menu items as displayed on the SoundBridge’s internal web page. Each menu item is separated with a back-slash (\). These menus MUST be ordered in the same order that they appear in the English translation. Translated menu items cannot contain the back-slash character. Items in this category:
SR_WP_TIME_MENU_ITEMS
SR_WP_TZ_MENU_ITEMS
SR_WP_DST_MENU_ITEMS
Date and time formats
The following items are encoded date/time formats, which use the tilde (~) character as the separator:
SR_SM_DATE_FMT
SR_SM_TIME_FMT
These items act as default formats, used by the SoundBridge automatically when the given language is selected -- provided that the user has not customized their date/time settings. If the user has customized, their customizations will override whatever is done here. These are formatted as follows:
SR_SM_DATE_FMT
prefix~separator1~separator2~separator3~separator4~menuselection1~menuselection2~menuselection3~menuselection4
SR_SM_TIME_FMT
separator1~separator2~separator3~separator4~menuselection1~menuselection2~menuselection3~menuselection4~AMindicator~PMindicator
Note that any time one of the separator, prefix or AM/PM items is to be empty, it is represented by the word "empty". Do not just leave the field blank (~~) or it will not work properly.
The menuselection items are numbers, and correspond to the following lists:
Date:
0: Leave Blank
1: Long day
2: Short day
3: Long month
4: Short month
5: Numeric month
6: Numeric month with leading zero
7: Day of the month
8: Day of the month with leading zero
9: Long year
10: Short year
Time:
0: Leave blank
1: Hour (12-hour)
2: Hour (12-hour with leading zero)
3: Hour (24-hour)
4: Hour (24-hour with leading zero
5: Minute
6: Second
7: AM/PM indicator
You may want to study the existing localizations to understand how this feature works.
Alphabetic sort order
The SR_LOC_SORT_ORDER contains a special string that determines how text is sorted. The string can contain any alphabetic character in the LATIN-1 character set. No other numeric, symbolic, or non-LATIN-1 characters are allowed.
For Japanese, Chinese or other languages that do not use the LATIN-1 character set, sorting is performed in Unicode code-point order. Unless such a language also requires special sorting rules for the LATIN-1 characters, you can omit localization of this string.
The format of the string is as a list of groups of characters, where the groups are separated by a single space character between them. Each character in a given group is treated as equivalent when sorting. The groups are listed in descending order. In other words, characters in the first group will sort to the top of a list, followed by characters in a second group, and so on.
As an example, an abbreviated section of this string appears below:
eng “AÀÃÂÃÄÅ B CÇ D EÈÉÊË F G H ... aà áâãäå b cç d ...â€
According to this string, any capital letter “A†with a diacritical marking is treated equivalently to the unmodified letter “Aâ€. All variants of the letter A sort before the letter B, which sorts before the letter C and its variant, and so on. Lower-case letters sort after any upper-case letter.
When formatting this string, you should assume that upper-case letters always sort before lower-case letters, even though some areas of the SoundBridge user interface override this behavior to do a case-insensitive sort.
SoundBridge does not currently support "special" sorting rules, such as compound characters ("ll", "ch", etc) or French accented sorting rules.
Keyboard text entry
SR_LOC_TE_KBD contains a special string which is used to present the on-screen text-entry keyboard. This string may contain any alphabetic character in the LATIN-1 character set. No other numeric, symbolic or non-LATIN-1 characters are allowed. The first grouping of letters is the lower-case alphabet. The second grouping is the upper-case alphabet. These generally should have the same number of characters. The third grouping contains any “extended†characters, and should contain any LATIN-1 lower-case alphabetic characters not already listed in the other lists. These three groups should be separated with exactly one normal space character between them.
Entry of non-LATIN-1 characters is not possible. For languages that do not use LATIN-1 characters, you may omit localizing this string.
Preset strings
The SoundBridge automatically builds names for new Presets when they are saved. These strings have special tokens in them that are replaced by information from the Preset. For example:
- Code: Select all
# %1 is Genre, 2 is Album, 3 is Artist, 4 is Composer
SR_PS_GENRE_ALBUM
eng "%1 tracks on %2"
spa "Archivos %1 en %2"
jpn "%2 ? %1 ????"
Notice the comment that explains what %1 through %4 map to. In English, this string will say, for example "Rock tracks on The Joshua Tree". Note, though, that in Japanese, the album will come before the genre. This is why the numbers are used instead of the simple %s string substitution. When localizing these Preset strings, pay attention to the comment explaining what %1 through %4 mean, and follow the model of the other languages.
That's it! Questions are welcome.
Or "Attache ta tuque avec de la broche!" for a French Quebec touch...
