Localization How-to Author: Kevin K.M. Chiu Copyright 2000, Cobalt Networks. All rights reserved. $Id: l10nHowTo.txt,v 1.2 2005/08/15 04:15:01 dodell Exp $ Overview ======== This document describes how to localize products based on the Sausalito software architecture. The anticipated readers of this document are translators, engineers and project managers of localization projects. Therefore, this document is not super technical, but understanding of the Sausalito architecture helps. The Basics ========== Module ------ Sausalito-based products are composed of the Sausalito platform and feature modules. Each of these modules are pretty much self contained and contains its own locale resources. Locale ------ It is important to know how to specify locales because it is used in many different places in Sausalito. They are specified as strings in the format: locale ::= lang-code [ '_' country-code [ '_' variant-code ] ] lang-code ::= two-letter ISO-639 language code (ie. 'ja') country-code ::= two-letter ISO-3166 country code (ie. 'JP') variant-code ::= a language variant code (ie. 'EUC'). For the complete ISO-639 language code list, see http://www.oasis-open.org/cover/iso639a.html. Complete ISO-3166 list can be found at http://www.normos.org/en/lists/iso/iso-3166.html. String File ----------- String files exist for the purpose of storing strings. These strings are used in various user interfaces from web GUI to LCD panel. They are the bulk of work for Sausalito localization projects because of the large number of strings within them. These strings are accessed by the I18n library of Sausalito. It supports the .po file format of GNU gettext utility. For details, read http://www.delorie.com/gnu/docs/gettext/gettext_toc.html. Generally, working on Sausalito localization projects does not need indepth understanding of GNU gettext. Understanding .po file format should be sufficient. In short, .po files contain message ID and message string pairs. Lines starting with "#" signs are comments. A simple example would be: # For the label msgid "fullName" msgstr "Full Name" # For the help msgid "fullName_help" msgstr "This field is for the full name of the user." "msgid" marks message IDs and "msgstr" marks message strings. For localization, only translate message strings. Because Sausalito reference strings by their message IDs, do not change message IDs. HTML File --------- Though not many, there are HTML files in Sausalito-based products that need to be localized. They either contain strings or locale-sensitive formatting elements. For example, fonts or even width of tables cells that hold strings can be locale-sensitive. Property File ------------- Some modules contain locale property files. They have file extension .prop. Each module can have one at most. These files store locale specific properties in a key value pair format of ": ". Comment lines start with "#". For example: # set to "yes" if this locale needs the sort name feature or "no" otherwise needSortName: no These files are used to fine tune locale specific feature options. mod_negotiation --------------- Working along with Sausalito is the Apache web server. It supports content negotiation. From localization's point of view, what it does is that it serves web content of different locales to to clients based on their locale preference. For example, if the web client prefers to view chinese content, when it requests a HTML file, the chinese version of the HTML file is served if available. The details about how mod_negotiation works are not important for Sausalito localization projects. The important thing to know is how to name web files so that they can be served correctly by mod_negotiation. For locale-sensitive web content, append the corresponding locale string as a file extension to the end of these files. Files that do not have the locale file extensions are fallback files. Let's give an example. If page.html, page.html.en and page.html.ja exist under the web root, when a web client with locale preference set to japanese requests http:///page, then page.html.ja is served. If the web client change its preference to english and request the same file, then page.html.en is served. If the preference is german, then page.html is served because it is the fallback. Of course, page.html can be a symbolic link to the desired file. If you are interested in mod_negotiation, its full documentation can be found at http://www.apache.org/docs/mod/mod_negotiation.html and http://www.apache.org/docs/content-negotiation.html. Style ----- The style system in Sausalito is locale-sensitive. This is because style properties like font family and font size can be different for different locales. Style properties are stored in style resource files. They are named with a .xml extension. Locale specific style properties can be placed in separate style resource files. Style properties in these files will override those specified in the locale-insensitive files. For example, for style True Blue, trueBlue.xml is and trueBlue.xml.ja is The font size for pages are going to be 10 points for japanese and 12 points for other locales. For all locales, the active link color remains the same. More more information about the format of the style property files and the style system, read Sausalito documentation. Working With Files ================== String File ----------- String files are located under the locale directory of each feature module. They have .po extensions. For example, the english string file for the base-ftp.mod module is base-ftp.mod/locale/en/ftp.po. Using the base-ftp.mod module example, these are steps taken to localize string files for it: - Make sure you are "root" user. If not, you have to login as "admin" user and use the "su" command. - Select an available source string file under the module to localize from. For example, base-ftp.mod/locale/en/ftp.po. English string files are usually available. You can also start with string files of other locales. - Make a directory for the target locale. For example, to translate into japanese, make a new base-ftp.mod/locale/ja directory with command "mkdir base-ftp.mod/locale/ja". - Copy the source file into the newly made target directory using command "cp base-ftp.mod/locale/en/ftp.po base-ftp.mod/locale/ja/ftp.po". - Translate all message strings within the target file. They are in the "msgstr" lines. Do not touch the "msgid" lines. Note that the strings are not escaped. "\" remains "\" and '"' cannot be used within strings. - Use the "make" command to build the module. This command needs to be performed at the root of the module. Therefore, "cd base-ftp.mod" before "make". Note that there can be errors reported. If that is the case, fix the file and do the command again until it is fixed. - The module built needs to be installed to the appropriate working directories. Use command "make install". Again, this needs to be performed at the root of the module. - Server desktop server needs to be notified with the string change if they are used on the web GUI using the restart operation. Use command "/usr/local/etc/rc.d/admserv restart". - If the string change is for the server desktop, login to it to verify the changed strings. If you are already logged in, refresh the page. Remember to set the locale preference of the login user to the target locale first. - If everything looks great, you are done! Otherwise, go back to the translation step. HTML File --------- HTML files usually locate under ui/web directory within modules. For example, for module base-ftp.mod, HTML files are under base-ftp.mod/ui/web/. Using the base-ftp.mod module example, these are steps taken to localize a HTML file, say, index.html: - Make sure you are "root" user. If not, you have to login as "admin" user and use the "su" command. - Select an available source HTML file. English HTML files (e.g. index.html.en) are usually available. - Make a new copy of the source HTML file to translate. For example, to translate into japanese, do "cp base-ftp.mod/ui/web/index.html.en base-ftp.mod/ui/web/index.html.ja" - Translate all strings in the new file. They are usually marked with tags. - Edit all locale-sensitive formatting elements. They are usually marked with tags. - Perform the "make install" command under the root of the module. This will copy the localized file into working directory. This also creates a symbolic link for the fallback HTML file to point to the english version (e.g. index.html -> index.html.en). - Login to server desktop to verify the changed HTML file. If you are already logged in, refresh the page. Remember to set the locale preference of the login user to the target locale first. - If everything looks great, you are done! Otherwise, go back to the translation step. Property File ------------- Property files locate under the locale directory. Modules may not have them. For example, english property file for base-ftp.mod is base-ftp.mod/locale/en/ftp.prop. To localize property files, follow these steps: - Make sure you are "root" user. If not, you have to login as "admin" user and use the "su" command. - Select an available source property file. English ones are usually available. - Make a new directory for the target locale. For example, to localize into japanese, do "mkdir base-ftp.mod/locale/ja". - Copy the source property to the new directory with command "cp base-ftp.mod/locale/en/ftp.prop base-ftp.mod/locale/ja/ftp.prop" - Edit the new property file. - Do "make install" under the module root directory to install the property file to the working directory. - Depending on the desirable effect of the properties changed, perform validation. - If outcome is not desired, go back to the edit step. Otherwise, you're done! Style File ---------- Style files locate under the gallery module within the style directory (i.e. gallery/style). Locale-sensitive ones are located under the locale directory (i.e. gallery/locale). To make locale specific styles for say, True Blue style (i.e. trueBlue.xml), into japanese, follow these steps: - Make sure you are "root" user. If not, you have to login as "admin" user and use the "su" command. - Copy trueBlue.xml from gallery/style into locale/ja. - Populate the new style file with locale specific properties. Of course, you need to follow the style file syntax. - Do "make install" under gallery root to install the new style file into working directory. - To test, login to server desktop and view pages where these styles properties are relevant. Remember to make sure locale perference of the login user is set to the target locale. - If outcome is not desired, go back to edit the style file again. Otherwise, you are done! FAQ === Q. There are "Permission denied" errors when I do "make", "make install" or other file operations. What is wrong? A. You may not be performing these operations as the "root" user. Only "root" user has the permission to access the working directories in the file system. Q. I've made changes to string files, did "make" and "make install". When I login to server desktop, nothing is changed. What happened? A. It may be that the web browser is caching old data. Try a super reload (Ctrl-reload for Netscape and IE for Windows). If that doesn't work, it may be that you have not restarted the server desktop server. In this case, do "/usr/local/etc/rc.d/admserv restart". Q. I see the translated strings look wrong and not readable on server desktop. When I view HTML source of the page on the browser, they look right. What is the problem? A. These strings may be surrounded by font tags that specifie locale specific fonts. For example, japanese do not have arial or helvetica fonts. Edit the according style files or HTML files to correct the problem. Building PKG ============