Diff for /books/www/chapters/ch11.html between versions 1.1 and 1.2

version 1.1, 2002/09/17 21:10:35 version 1.2, 2002/09/23 15:23:31
Line 20 Line 20
 <P><LI>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.<P>  <P><LI>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.<P>
 <P><LI>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.<P>  <P><LI>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.<P>
 <P><LI>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.<P></UL>  <P><LI>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.<P></UL>
<P>Recalling the architecture of the XPFE toolkit described in <A HREF="ch02.htm#77048">Chapter 2</A>, 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.<P>Recalling the architecture of the XPFE toolkit described in <A HREF="ch02.html#77048">Chapter 2</A>, 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.
 <H3><A NAME="77030"></A> For the Developer</H3>  <H3><A NAME="77030"></A> For the Developer</H3>
 <P>Many available  <!--INDEX localization:resources -->  <!--INDEX resources:localization --> 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. <!--INDEX newsgroups, localization -->  <!--INDEX development:localization resources -->  <P>Many available  <!--INDEX localization:resources -->  <!--INDEX resources:localization --> 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. <!--INDEX newsgroups, localization -->  <!--INDEX development:localization resources -->
 <P>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 <I>netscape.public.mozilla.l10n</I> and <I>netscape.public.mozilla.i18n</I> newsgroups are a great place to discuss these issues with other developers.  <P>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 <I>netscape.public.mozilla.l10n</I> and <I>netscape.public.mozilla.i18n</I> newsgroups are a great place to discuss these issues with other developers.
Line 40 Line 41
 <P>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.  <P>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.
 <H4><A NAME="77033"></A> Space management</H4>  <H4><A NAME="77033"></A> Space management</H4>
 <P>One of the  <!--INDEX localization:UI aesthetics, space management -->  <!--INDEX user interface:localization:space management -->  <!--INDEX design issues, user interfaces:localization and space management --> 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.  <P>One of the  <!--INDEX localization:UI aesthetics, space management -->  <!--INDEX user interface:localization:space management -->  <!--INDEX design issues, user interfaces:localization and space management --> 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.
<P>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 <A HREF="ch03.htm#77084">Chapter 3</A> for more information) and correct choice of widgets goes a long way in achieving this goal.<P>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 <A HREF="ch03.html#77084">Chapter 3</A> for more information) and correct choice of widgets goes a long way in achieving this goal.
 <P>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.  <P>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.
 <H4><A NAME="77034"></A> Help system</H4>  <H4><A NAME="77034"></A> Help system</H4>
 <P>If you  <!--INDEX help system, localization and -->  <!--INDEX localization:help system -->  <!--INDEX user interface:localization:help system --> 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.  <P>If you  <!--INDEX help system, localization and -->  <!--INDEX localization:help system -->  <!--INDEX user interface:localization:help system --> 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.
Line 252  srGetStrBundle("chrome://mypackage/local Line 254  srGetStrBundle("chrome://mypackage/local
 <H2><A NAME="77052"></A> Programming and Localization</H2>  <H2><A NAME="77052"></A> Programming and Localization</H2>
 <P>This section provides little nuggets of information, not necessarily related, that show how to work around common problems when programming locale-related information in your application. It strays a little from the main path of string replacement and translation, and the topics vary from recommended naming conventions for your string identifiers to locale in XBL bindings and what tools you can use to be more productive.  <P>This section provides little nuggets of information, not necessarily related, that show how to work around common problems when programming locale-related information in your application. It strays a little from the main path of string replacement and translation, and the topics vary from recommended naming conventions for your string identifiers to locale in XBL bindings and what tools you can use to be more productive.
 <H3><A NAME="77053"></A> Naming Conventions</H3>  <H3><A NAME="77053"></A> Naming Conventions</H3>
<P>The decision <!--INDEX programming localization:naming conventions -->  <!--INDEX localization:programming:naming conventions -->  <!--INDEX naming conventions, localization -->  of what to call your code internals emerged more than once in this book. In <A HREF="ch08.htm#77048">Chapter 8</A>, you decided the name of the component IDL interface IDL file and its associated implementation. In locale, it is the entity names and string identifiers contained in bundles.<P>The decision <!--INDEX programming localization:naming conventions -->  <!--INDEX localization:programming:naming conventions -->  <!--INDEX 
 naming conventions, localization -->  of what to call your code internals emerged more than once in this book. In <A HREF="ch08.html#77048">Chapter 8</A>, you decided the name of the component IDL interface IDL file and its associated implementation. In locale, it is the entity names and string identifiers contained in bundles.
 <P>Naming conventions in localization are useful because they provide some context to the translator. In this spirit, it is good for the reference to be as descriptive as possible. You can choose your route for naming or stick with the way that Mozilla does it. Examining the files in the Mozilla source base, common naming conventions for entities include the following:  <P>Naming conventions in localization are useful because they provide some context to the translator. In this spirit, it is good for the reference to be as descriptive as possible. You can choose your route for naming or stick with the way that Mozilla does it. Examining the files in the Mozilla source base, common naming conventions for entities include the following:
 <BLOCKQUOTE>id.label  <BLOCKQUOTE>id.label
 id.tooltip  id.tooltip
Line 359  tooltip="&amp;flyBtn.tooltip;" /&gt;</PR Line 362  tooltip="&amp;flyBtn.tooltip;" /&gt;</PR
 <P>The binding in <A HREF="#77020">Example 11-7</A> illustrates a binding whose content inherits its locale from the bound element. The attributes used on the bound element, namely <TT>title</TT> and <TT>author</TT>, are descriptive, enabling the author to be specific about what they are setting a value to. The rest is taken care of in the binding, where the <TT>inherits</TT> attribute sets the value on the anonymous content to the value of the more descriptive attributes on the bound element. You can retrieve the values or set them by using the getter and setter.  <P>The binding in <A HREF="#77020">Example 11-7</A> illustrates a binding whose content inherits its locale from the bound element. The attributes used on the bound element, namely <TT>title</TT> and <TT>author</TT>, are descriptive, enabling the author to be specific about what they are setting a value to. The rest is taken care of in the binding, where the <TT>inherits</TT> attribute sets the value on the anonymous content to the value of the more descriptive attributes on the bound element. You can retrieve the values or set them by using the getter and setter.
 <BLOCKQUOTE><HR><A NAME="92113"></A> Localization  <!--INDEX localization:tools --> Tools  <BLOCKQUOTE><HR><A NAME="92113"></A> Localization  <!--INDEX localization:tools --> Tools
 <P>To translate your XUL interface strings, just change the text that corresponds to your entity reference or string bundle value. For a small application, this step should be simple, but for large applications, it can be a big task.  <P>To translate your XUL interface strings, just change the text that corresponds to your entity reference or string bundle value. For a small application, this step should be simple, but for large applications, it can be a big task.
<P>The good news is that tools are available to help localize your applications. The most popular tool is MozillaTranslator, which is discussed in more detail in <A HREF="appb.htm#77021">Appendix B</A>.<P>The good news is that tools are available to help localize your applications. The most popular tool is MozillaTranslator, which is discussed in 
 more detail in <A HREF="appb.html#77021">Appendix B</A>.
 <P>There is also a handy command line utility for Unicode conversion called nsconv, bundled in the Mozilla <I>bin</I> folder in any distribution. (If you are unfamiliar with Unicode, the section <A HREF="#77067">"XPFE and Unicode</A>" later in this chapter provides more information.) Although it is broken at the time of this writing, it is worth mentioning. Let's look at a simple conversion of ASCII text to UTF-8:  <P>There is also a handy command line utility for Unicode conversion called nsconv, bundled in the Mozilla <I>bin</I> folder in any distribution. (If you are unfamiliar with Unicode, the section <A HREF="#77067">"XPFE and Unicode</A>" later in this chapter provides more information.) Although it is broken at the time of this writing, it is worth mentioning. Let's look at a simple conversion of ASCII text to UTF-8:
 <PRE>&lt;!ENTITY PrintPreviewCmd.label    "Print Preview"&gt;</PRE>  <PRE>&lt;!ENTITY PrintPreviewCmd.label    "Print Preview"&gt;</PRE>
 Replace the string in the entity with the Spanish version:  Replace the string in the entity with the Spanish version:
Line 408  Using the NCR or CER value as well is al Line 412  Using the NCR or CER value as well is al
   
 <P>The folder that is registered is the language folder, which is what has to be changed on an install. Thus, the URL <I>chrome://package/locale</I> actually points to <I>package/locale/en-US</I> or whichever language is turned on at the time. The language folder may in turn include subfolders that contain logical units for your application.  <P>The folder that is registered is the language folder, which is what has to be changed on an install. Thus, the URL <I>chrome://package/locale</I> actually points to <I>package/locale/en-US</I> or whichever language is turned on at the time. The language folder may in turn include subfolders that contain logical units for your application.
 <H3><A NAME="77062"></A> Interaction with the Chrome Registry</H3>  <H3><A NAME="77062"></A> Interaction with the Chrome Registry</H3>
<P>As pointed  <!--INDEX localization:chrome registry -->  <!--INDEX chrome:localization:registry --> out in <A HREF="ch06.htm#77063">Chapter 6</A>, your packages directories need to be registered as chrome with the chrome registry. The first step is to ensure that the entry for your package component is in the file <I>chrome.rdf</I> in the root chrome directory.<P>As pointed  <!--INDEX localization:chrome registry -->  <!--INDEX chrome:localization:registry --> out in <A HREF="ch06.html#77063">Chapter 
 6</A>, your packages directories need to be registered as chrome with the chrome registry. The first step is to ensure that the entry for your package component is in the file <I>chrome.rdf</I> in the root chrome directory.
 <P>A <I>resource:/</I> URL points to the folder for your files to be picked up and recognized by the chrome mechanism and accessed via <I>chrome://</I> URLs in your application code. The locale is no exception.  <P>A <I>resource:/</I> URL points to the folder for your files to be picked up and recognized by the chrome mechanism and accessed via <I>chrome://</I> URLs in your application code. The locale is no exception.
 <PRE>&lt;RDF:Description about="urn:mozilla:locale:en-US:xfly"  <PRE>&lt;RDF:Description about="urn:mozilla:locale:en-US:xfly"
 c:baseURL="resource:/chrome/xfly/locale/en-US/"&gt;  c:baseURL="resource:/chrome/xfly/locale/en-US/"&gt;
Line 420  c:localeVersion="0.1.0.0" Line 425  c:localeVersion="0.1.0.0"
 <P>Language d <!--INDEX localization:distrubution issues -->  <!--INDEX distribution:localization issues --> istribution may not be an issue for you. If, for example, your application were only going to be localized into a finite number of languages, bundling each of them up with the main installer would be most convenient. If, however, the need for new language versions arises at various intervals in the release process, you need to find a way to make them available and install them on top of an existing installation.  <P>Language d <!--INDEX localization:distrubution issues -->  <!--INDEX distribution:localization issues --> istribution may not be an issue for you. If, for example, your application were only going to be localized into a finite number of languages, bundling each of them up with the main installer would be most convenient. If, however, the need for new language versions arises at various intervals in the release process, you need to find a way to make them available and install them on top of an existing installation.
 <P>For example, as more people from various locations in the world are becoming aware of the Mozilla project, they want to customize it into their own language. Here are the steps that you need to take to set up your version.  <P>For example, as more people from various locations in the world are becoming aware of the Mozilla project, they want to customize it into their own language. Here are the steps that you need to take to set up your version.
 <OL><P><LI>Register as a contributor and set up the resources that you need, if any (web page, mailing list). This will ensure that you are added to the project page on the mozilla.org site.<P>  <OL><P><LI>Register as a contributor and set up the resources that you need, if any (web page, mailing list). This will ensure that you are added to the project page on the mozilla.org site.<P>
<P><LI>Get a copy of Mozilla to test either via a binary distribution or by downloading and building your own source (see <A HREF="appa.htm#90096">Appendix A</A> for more information).<P><P><LI>Get a copy of Mozilla to test either via a binary distribution or by downloading and building your own source (see <A 
 HREF="appa.html#90096">Appendix A</A> for more information).<P>
 <P><LI>Translate the files.<P>  <P><LI>Translate the files.<P>
 <P><LI>Package your new files for distribution.<P>  <P><LI>Package your new files for distribution.<P>
 <P><LI>Test and submit your work.<P></OL>  <P><LI>Test and submit your work.<P></OL>
<P>Step 4, the packaging of the new language pack, is discussed next. Mozilla's Cross-Platform Install (XPI) is the ideal candidate for achieving this packaging. This method is discussed extensively in <A HREF="ch06.htm#77063">Chapter 6</A>. This distribution method provides great flexibility and has the benefit of being native to Mozilla, thus bypassing the search for external install technologies for your application.<P>Step 4, the packaging of the new language pack, is discussed next. Mozilla's Cross-Platform Install (XPI) is the ideal candidate for achieving 
 this packaging. This method is discussed extensively in <A HREF="ch06.html#77063">Chapter 6</A>. This distribution method provides great flexibility and has the benefit of being native to Mozilla, thus bypassing the search for external install technologies for your application.
 <H4><A NAME="77064"></A> The anatomy of an install script</H4>  <H4><A NAME="77064"></A> The anatomy of an install script</H4>
 <P><A HREF="#77024">Example 11-9</A> presents <!--INDEX localization:install scripts -->  <!--INDEX installation:localization and install scripts -->  <!--INDEX scripts:install, localization and -->  a script that is based on the Mozilla process that distributes localized language packs. It presumes that there is a single JAR file for the language that is installed and registered in the Mozilla binary's chrome root.  <P><A HREF="#77024">Example 11-9</A> presents <!--INDEX localization:install scripts -->  <!--INDEX installation:localization and install scripts -->  <!--INDEX scripts:install, localization and -->  a script that is based on the Mozilla process that distributes localized language packs. It presumes that there is a single JAR file for the language that is installed and registered in the Mozilla binary's chrome root.
 <P>The XPI archive consists of the JAR file in a <I>bin/chrome</I> directory and the <I>install.js</I> file, together in a compressed archive with an <I>.xpi</I> extension. Simply clicking on a web page link to this file invokes the Mozilla software installation service and installs your language. For convenience, inline comments in <A HREF="#77024">Example 11-9</A> explain what is happening.  <P>The XPI archive consists of the JAR file in a <I>bin/chrome</I> directory and the <I>install.js</I> file, together in a compressed archive with an <I>.xpi</I> extension. Simply clicking on a web page link to this file invokes the Mozilla software installation service and installs your language. For convenience, inline comments in <A HREF="#77024">Example 11-9</A> explain what is happening.

Removed from v.1.1  
changed lines
  Added in v.1.2


FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>