Localization How-to

Author: Kevin K.M. Chiu
Copyright 2000, Cobalt Networks.  All rights reserved.
$Id: l10nHowTo.txt,v 1.6 2001/01/25 23:50:58 kevin 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 "<key>: <value>". 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://<IP address>/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

<styleResource name="[[trueBlue.trueBlue]]">
  <style id="Page">
    <property name="aLinkColor" value="#0033CC"/>
    <property name="fontSize" value="12pt"/>
  </style>
</styleResource>

and trueBlue.xml.ja is

<styleResource name="[[trueBlue.trueBlue]]">
  <style id="Page">
    <property name="fontSize" value="10pt"/>
  </style>
</styleResource>

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
  "/etc/rc.d/init.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
  <!-- locale-sensitive --> tags.
- Edit all locale-sensitive formatting elements. They are usually marked with
  <!-- locale-sensitive --> 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
   "/etc/rc.d/init.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
============
