Tài liệu Creating Applications with Mozilla-Chapter 11. Localization-P1 pptx

Chapter 11. Localization-P1
This chapter describes how to use Mozilla's internationalization (I18N) and
localization (L10N) technologies to make applications usable by people
around the world. Because the Mozilla community (and the Internet
community in general), is global, it is vital to be able to cross language
barriers by localizing your application and making it available to a wider
audience.
In this chapter, you are given step-by-step instructions on how to change the
visible text for your application in the XUL interface and how to handle
nonstatic strings that arise from dynamic string handling in other areas of
your application code.
While the basic technologies that are used are not new, Mozilla is innovating
in areas such as Unicode support and quick access language pack installs.
The information in this chapter about the internationalization
( and localization
( projects will give you a
solid foundation for what is possible in your own application.
11.1. Localization Basics
Before learning how to localize your Mozilla application, it's useful to run
through some of the high-level goals and features of the Mozilla
internationalization and localization projects. First, here are some
definitions:
Internationalization (I18N)
The design and development of software to function in a particular
locale. The shorthand term, I18N, refers to the 18 letters between the
initial "i" and final "n."
Localization (L10N)
The modification of software to meet the language of a location and
the adaptation of resources, such as the user interface (UI) and
documentation, for that region. L10N is an acronym for localization
and refers to the 10 letters between the initial "l" and final "n."

Locale
"A set of conventions affected or determined by human language and
customs, as defined within a particular geo-political region. These
conventions include (but are not necessarily limited to) the written
language, formats for dates, numbers and currency, sorting orders,
etc.," according to the official Mozilla document found at

Locale in the context of this chapter is related specifically to the display of
text in the user interface. The focus will be on UI localization of XUL files
and strings contained in JavaScript and C++ files, as well as the methods
employed for localization.
Here are some main features of the Mozilla internationalization capabilities,
which are relevant to the user front end application level:
• Mozilla is Unicode-enabled for Latin-based languages, Cyrillic,
Greek, Chinese, Japanese, and Korean. Mozilla widgets and HTML
rendering can support the input and display of these languages.
Unicode-enabling for other languages and character sets is an ongoing
process.
• Mozilla can be easily localized into different languages, even if not
supported by the underlying operating system.
• Most Mozilla localization work involves translating strings as entities
in Document Type Definition (DTD) format and properties file format
(an idea taken from Java), which are based on open standards.
• Localization can be done once and run on Windows, Macintosh, Unix,
and other platforms something we have come to expect from the
Mozilla framework. This is a great time saver, and indeed a cost saver
if you come at it from that perspective.
• Mozilla supports BIDI, the display and input of text in a bidirectional
format for such languages as Arabic and Hebrew, yet the capabilities
for this in the UI were not mature when we were writing this book.

• The UI locale DTD files use UTF-8 as the default encoding for
translated items. Mozilla then maps to Unicode or non-Unicode fonts,
depending on which platform you're running on or what fonts you
installed in your system. You are encouraged to encode your DTD
files as UTF-8 when possible.
Recalling the architecture of the XPFE toolkit described in Chapter 2
, the
locale component can be easily plugged in and out of the application that
you are working on without impacting any other components. This
functionality is ideal, for instance, for people with linguistic skills and less
experience with technical issues to become involved in a Mozilla-related
project.
11.1.1. For the Developer
Many available resources show you how to help localize an existing
application into a specific language or to find out how to add localization
support to your own application.
The Mozilla Localization Project hosts various localization teams and
provides help whenever possible. The Mozilla community includes a
discussion group that uses many languages to discuss Mozilla development
issues. The netscape.public.mozilla.l10n and netscape.public.mozilla.i18n
newsgroups are a great place to discuss these issues with other developers.
When developing an application, some words and phrases that developers
like to hear (according to the Mozilla organization, at
are: standards
compliant, simple, leveragable, portable, extensible, separable, consistent,
dynamic, valid, parser friendly, invisible (part of the XUL authoring
process), and efficient. The following sections will help you understand how
these terms and goals impact the chosen technologies and how to use those
technologies. The ultimate aim is to help you localize your application
easily.

11.1.2. Files and File Formats
Here are the main file types you'll see when learning about locale and that
you will use when localizing your Mozilla application. A good home for all
of these resources is in the locale area of the application chrome.
DTD (.dtd)
Files containing entities that host the strings from XUL content files.
Property (.properties) or string bundles
Files containing strings that are accessed by JavaScript, C++, and
possibly other scripting or component files.
RDF
RDF files are described in XML syntax, so use entities.
HTML and text
Suitable for long text, HTML and XML documents and other content
that needs to be localized.
The next two sections will help you start localizing your application. The
sections focus on DTD files and string bundles, which are the core formats
for XUL-localizable content. Before getting started, here is a review of some
general principles that might help you design and implement the locale
component.
11.1.3. UI Aesthetics and Principles
To put locale in context, this section looks at some issues you may encounter
when localizing your Mozilla application. Some are universal principles and
others are unique to the environment. This reference is by no means
exhaustive, but it contains some scenarios and tips the authors came across
in their experience with locale in Mozilla.
11.1.3.1. Space management
One of the guiding principles in UI design is for your interface to not get too
crowded. Although estimates are not specific, it is wise to leave about 30
percent expansion space in your window and dialogs. To achieve this
flexibility, you have to ensure that the XUL window has ample space in the

first place for all the widgets to fit.
More specifically, the application needs to have space for widgets to expand
or contract without detracting from the overall look and feel. Intuitive use of
the XUL box model (refer to Chapter 3
for more information) and correct
choice of widgets goes a long way in achieving this goal.
The factors that can cause this space to be filled include using
languages/character sets that are more verbose than the one that was there
originally, and the users changing their font size settings. Some safeguards
that have been built into Mozilla already handle this problem. Much of it is
done in CSS, but other methods are available. The section "Language
Quirks," later in this chapter, outlines one of these methods.
11.1.3.2. Help system
If you choose to integrate a Help system into your application, a localizable
resource will be most content. Opinions differ within technical writing
circles, but having screenshots in your documents is generally not
considered advantageous. For example, they can get out of date easily in the
constantly evolving world of software, or they need to be retaken frequently
when new features are added to the UI.
11.1.3.3. Tooltips
Tooltips are a sometimes overlooked yet valuable way of relaying
information to the user. They can be used as an alternative to a help system
if you are looking for something simpler. They can also expand an
explanation of something that was annotated in the UI text. Sometimes text
can have multiple meanings in context, and expanding it with a tooltip can
clear up any confusion. In an editor or multifile browser, for example, you
might have a find button. A tooltip can clear up the confusion about whether
the results of the action searches in the current file or in all files.
Most XUL widgets support tooltips. Implementation is as straightforward as
adding a tooltip attribute to the widget with an associated value. For it to

be localizable, it must be in the form of a DTD entity.
<tab id="config" label="&config.label;"
tooltip="&config.tooltip;" />
The Section 11.2.1
section, later in this chapter, provides more information
on the rationale for using entities and how to insert them into XUL content.
11.1.3.4. Grammar
In any user interface, there is limited screen space. When possible, however,
provide complete or near-complete sentences. These sentences are better
than using text based on phrases or acronyms. They provide meaning to the
translator and clearer instructions to the user.
11.1.3.5. Commenting
Commenting was mentioned before, but is worth stressing again. The
translators may have not even seen the software that you are working on, but
you hope that is not the case! Commenting is very useful for giving context
and flagging strings that should not be commented. You can comment your
HTML, XML, or DTD files by wrapping it in a <! comment >
block.
<! NOTE to Translators: Do NOT change the next
string >
<!ENTITY appName.label "My Application">
Note that a bundle file uses the # notation at the beginning of each line to
signify a comment.
# This text is used in the view menu for launching
the page choices dialog
pageChoices=Go To
11.1.3.6. Web resources
Localizable resources are not only strings of text that need to be translated
into different languages; they are any variable information that is liable to
change over the lifetime of your application. The handling of URLs is a case

in point. You may have references interspersed throughout your UI that
point to web resources. These references can be explicit listings or widgets
that, once activated, launch a client to bring you to a certain location.
Images are another resource commonly used in documentation. A tutorial on
your application may have screenshots of the UI in action. If you do use
images, keep an eye out for localizable content in them.
11.2. DTD Entities
Entities in XUL work the same way as they do in any other XML
application. They are used to reference data that was abstracted from the
content. This process encourages reuse of data, but in the context of
Mozilla's XPFE, it is used to extract visible text in interface widgets. This
extraction ensures that the content can remain untouched during the
localization process.
11.2.1. Inserting Entities
Example 11-1 shows how to put DTD entities into your XUL code by using
attribute values for the text of a menu item (label) and the keyboard
access shortcuts (accesskey). The syntax requires that an entity be placed
in quotes as the value of the attribute. This is a useful example because it
highlights the localization of a widget label, which is common to many
widgets, and a supplementary attribute, which, in this case, is an
accesskey.
Example 11-1. XUL menu with entity references for text and accesskeys
<menu label="&menuFile.label;"
accesskey="&menuFile.accesskey;">
<menupopup>
<menuitem accesskey="&menuNew.accesskey;"
label="&menuNew.label;"
oncommand="doNew( );"/>
<menuitem accesskey="&menuOpen.accesskey;"
label="&menuOpen.label;"

oncommand="doOpen( );"/>
<menuseparator />
<menuitem accesskey="&menuClose.accesskey;"
label="&menuClose.label;"
oncommand="doClose( );"/>
<menuitem accesskey="&menuSave.accesskey;"
label="&menuSave.label;"
oncommand="doSave( )"/>
<menuitem accesskey="&menuSaveAs.accesskey;"
label="&menuSaveAs.label;"
oncommand="doSaveAs"/>
<menuseparator />
<menuitem accesskey="&menuPrint.accesskey;"
label="&menuPrint.label;"
oncommand="doPrint( );"/>
<menuseparator />
<menuitem accesskey="&menuExit.accesskey;"
label="&menuExit.label;"
</menupopup>
</menu>
Note that each entity in Example 11-1
has a text value associated with it in
the DTD entities declarations. The entity that appears on the menu is
&menuFile.label;. Note that this entity mirrors the correct syntax for
referencing a value, which is: &get.text;.
The entity reference (or name, in this context) must be preceded by an
ampersand (&) and end with a semicolon (;). The period is optional, but
conventional. Typically, the period separates the entity's element or target
(menuFile) from the type of entity (label). Refer to theSection 11.4

section later in this chapter for more information on naming conventions.
For some widgets, including <description> and <label>, the entity
can be placed inside the element tags, as opposed to being values of
attributes.
<description>&explanation.text;</description>
Table 11-1
represents the DTD files that accompany the XUL content in
Example 11-1
. Two languages, English and Spanish, are separated into
different files. These files have the same name as the DTD file referenced in
the XUL file that contains the entities. However, each file for every different
language exists in a separate locale folder. Each entry, or entity, in the DTD
file has a name that matches the name referenced in the XUL and a value to
be filled in for that entity. The value is enclosed in quotes. When generating
these files, you will need to create the file only once and copy it to a
different directory where you can replace the values in the entities. A good
tool would carry out this process for you. Refer to the Localization Tools

sidebar later in the chapter for more information.
Table 11-1. Entity definitions for the XUL menu
English DTD Spanish DTD
<!ENTITY menuFile.label
"File">
<!ENTITY menuNew.label
"New">
<!ENTITY menuOpen.label
"Open ">
<!ENTITY menuClose.label
"Close">
<!ENTITY menuSave.label

<!ENTITY menuFile.label
"Archivo">
<!ENTITY menuNew.label
"Nuevo">
<!ENTITY menuOpen.label
"Abrir Archivo ">
<!ENTITY menuClose.label
"Cerrar">
<!ENTITY menuSave.label
English DTD Spanish DTD
"Save">
<!ENTITY menuSaveAs.label
"Save As ">
<!ENTITY menuPrint.label
"Print ">
<!ENTITY menuExit.label
"Exit">
<!ENTITY
menuFile.accesskey "f">
<!ENTITY
menuNew.accesskey "n">
<!ENTITY
menuOpen.accesskey "o">
<!ENTITY
menuClose.accesskey "c">
<!ENTITY
menuSave.accesskey "s">
<!ENTITY
menuSaveAs.accesskey "a">
<!ENTITY

menuPrint.accesskey "p">
<!ENTITY
"Salvar">
<
!ENTITY menuSaveAs.label
"Salvar Como ">
<!ENTITY menuPrint.label
"Imprimir ">
<!ENTITY menuExit.label
"Salir">
<!ENTITY
menuFile.accesskey "a">
<!ENTITY
menuNew.accesskey "n">
<!ENTITY
menuOpen.accesskey "o">
<!ENTITY
menuClose.accesskey "c">
<!ENTITY
menuSave.accesskey "s">
<!ENTITY
menuSaveAs.accesskey "a">
<!ENTITY
menuPrint.accesskey "i">
<!ENTITY
English DTD Spanish DTD
menuExit.accesskey "x"> menuExit.accesskey "r">
Figure 11-1 shows the resulting XUL menus. There can only be one value
for each entity and only one language taking precedence, or appearing in the
UI, at a time.

Figure 11-1. Localized menus in English and Spanish

This example presents only two languages, but theoretically, you can have as
many languages as you require. The locale-switching mechanism and the
chrome registry must determine which one should be used, which is
explained later in the section "The Chrome Registry and Locale."
11.2.2. External and Inline Entities
You may ask, how are the entities accessed? You can associate the DTD
with your XUL file in two ways. The first is internally, which involves
wrapping the strings in a DTD data type enclosure by using the DOCTYPE
declaration.
<!DOCTYPE window [
<!ENTITY windowTitle.label "Greetings">
<!ENTITY fileMenu.label "File">
]>
The second is an external DTD file, which is associated with your XUL that
also uses the DOCTYPE declaration, and a reference pointing to the file:
<!DOCTYPE window SYSTEM
"chrome://xfly/locale/xfly.dtd">
The node referenced in the DOCTYPE declaration is usually followed by the
XUL document's root node. In this case, it is window, but can be other
elements like page or dialog (however, it is not actually validated so it
can be any value).
If you have a small application, the DTD files can reside in the same folder
as your XUL files, but putting them into their own locale directory within
your chrome structure is good practice.
Consider the main Editor window in Mozilla. Its declaration in Example 11-
2 is flexible enough to associate multiple DTD files with your content.
Example 11-2. The Editor's Doctype definitions
<!DOCTYPE window [

<!ENTITY % editorDTD SYSTEM
"chrome://editor/locale/editor.dtd" >
%editorDTD;
<!ENTITY % editorOverlayDTD SYSTEM
"chrome://editor/locale/editorOverlay.dtd" >
%editorOverlayDTD;
<!ENTITY % brandDTD SYSTEM
"chrome://global/locale/brand.dtd" >
%brandDTD;
]>
The declaration first stores the document associated with the chrome URL in
an associated parameter entity. It then simply uses it. XML does not have a
one-step way of storing and using the entity as in other languages. In other
words, the declaration is the equivalent of the import foo in Python, or
#include "foo.h" in C.
Certain localizable resources lend themselves to reuse. It makes sense to use
the same strings across different content, which explains the inclusion of a
DTD file in more than one XUL document. In Mozilla, this includes brand
information, build ID numbers, and help resources.
Which is more appropriate to use: internal or external entities? Using the
external approach is preferable because the content (XUL) does not have to
be touched during the translation process. If someone opts to create a tool to
extract and/or insert strings, their job would be much easier if they had to
parse one less file type. This may remove context somewhat, but it can be
overcome by actively commenting the DTD file.
11.3. String Bundles
String bundles are flat text files that contain text for the UI that is accessed
in JavaScript, C++, and theoretically any language that fits within the
Mozilla framework. These bundles are strings that can be presented visually
to the user via some functionality in the application at any time. This may be

anything from a dynamically changing menu item to an alert box, or from a
URL to a placeholder that is filled depending on the context in which it is
accessed. The bundle files are given an extension of .properties and
they commonly reside in the locale directory with the DTD files.
A user interface can use one or more string bundles, each of which is defined
in a <stringbundle> element and surrounded by a
<stringbundleset> element. Example 11-3
contains the bundles used
by the Mozilla browser.
Example 11-3. String bundles used by the Mozilla browser
<stringbundleset id="stringbundleset">
<stringbundle id="bundle_navigator"

src="chrome://navigator/locale/navigator.properties
"/>
<stringbundle id="bundle_brand"

src="chrome://global/locale/brand.properties"/>
<stringbundle id="bundle_navigator_region"
src="chrome://navigator-
region/locale/region.properties"/>
<stringbundle id="bundle_brand_region"
src="chrome://global-
region/locale/region.properties"/>
<stringbundle id="findBundle"

>
</stringbundleset>