Tài liệu Creating Applications with Mozilla-Chapter 11. Localization-P2 ppt

Chapter 11. Localization-P2 As you can see from their names and their locations in the chrome, each bundle serves a different purpose. They include a file that contains the bulk of the strings for the browser (navigator.properties), a file that includes branding strings, and a couple of files for regional information. This model is useful if you need to output many strings to the UI from your source code and would like to organize them into meaningful groups. 11.3.1. Inside a Bundle A string bundle (.properties) file has a very simple format. It contains one or more lines that have the identifier associated with the localizable string. The format of a string bundle string with an identifier is: Identifier=String The format for comments in a bundle file requires the hash notation (#). Comments are useful for notifying translators of the context of strings, or flagging a string that should be left as is and not localized. Comments in properties files are formatted in the following manner. # DO NOT TRANSLATE applicationTitle=xFly Spaces in bundles are treated literally spaces between words are observed, with the exception of the start and the end of the string. The next section shows the methods and properties specific to the <stringbundle> element that are available to you when you use it. The implementations are contained in the binding for the element. 11.3.2. String Bundle Methods and Properties Defining your bundle in XUL and then creating the file with the values is only half the story. This section shows how to extract the values from the bundle and place them in UI. The language of choice in these examples is JavaScript. This process is necessary when you have to change values in the UI because DTD entities can not be updated dynamically. 11.3.2.1. Methods Our bundle is defined in XUL like this: <stringbundle id="bundle_xfly" To access the methods of the bundle object in your script, you have to get a handle on the XUL element by using its id. First declare the variable globally that will be holding the bundle: var xFlyBundle; Then assign the variable to the bundle. A good place to do this is in the load handler function of your XUL window, or in the constructor for your binding if you are using it from there: xFlyBundle = document.getElementById("bundle_xfly"); Now that you have access to the bundle, you can use the available methods to retrieve the strings. The two main functions are getString and getFormattedString. 11.3.2.1.1. getString The most straightforward string access method, getString, takes one parameter (namely the identifier of the string) and returns the localizable string value for use in the UI: var readonly = xFlyBundle.getString(`readonlyFile'); alert(readonly); The string bundle entry looks like this: readonlyfile=This file is read only 11.3.2.1.2. getFormattedString This function takes an extra parameter an array of string values, which are substituted into the string in the bundle. Then the full string with the substituted values is returned: var numFiles = numberInEditor numFilesMsg = xflyBundle.getFormattedString("numFilesMessage", [numFiles]); You can have more than one value replaced in the string, each one delimited within the square brackets by using a comma: fileInfo = xflyBundle.getFormattedString("fileInformation", [fileName, fileSize]); The string bundle entry looks like this: flyFileInformation=The file is called %1$s and its size is %2$s The %x numerical value refers to the ordering of the values to be substituted in the string. The type of the value is determined by the dollar ($) symbol. In this case, there are two possibilities $s is a string value and $d is an integer value. 11.3.2.2. Properties Some binding properties that are exposed to your script accompany the methods. These properties are not often needed for routine retrieval of string values, but are useful to know nonetheless if you ever need to discover or share the meta information related to your bundle and locale. 11.3.2.2.1. stringBundle This property is the string bundle object that queries the nsIStringBundleService interfaces and initializes the XPCOM interface, making methods available to it. It is the direct way of getting a string from a bundle: var appBundle = document.getElementById("bundle_app"); return appBundle.stringBundle.GetStringFromName("chapter11 "); 11.3.2.2.2. src This property is the attribute used to get and set the properties file that will be used as a string bundle: var appBundle = document.getElementById("bundle_app"); dump("You are using the properties file " + appBundle.src); 11.3.3. Creating Your Own Bundle The implementation for setting up your string bundle just described is hidden from the XUL author. You only need to point at the bundle you want to use by using the source attribute. There is however, an alternative way to do this if you do not favor using <stringbundle> or would like to extend that binding. The alternative is to use utility routines that come bundled with Mozilla and are contained in a string resources JavaScript file: strres.js. With this file, creating a bundle is a three-step process. 1. Include the JavaScript file: <script type="application/x-javascript" 1. Set up your bundle: var bundle = srGetStrBundle("chrome://mypackage/locale/mypackage .properties"); 1. Access the strings: var greeting = bundle.GetStringFromName( "hello" ); The result retrieves the string corresponding to "hello" in your bundle file and is the equivalent of the getString call when using the XUL bundle method. If your chrome is independent of Mozilla's chrome and you do not want to use their UI files, you can create the bundle directly by using the nsIStringBundleService XPCOM interface, as seen in Example 11-4 . Example 11-4. Creating the bundle via XPConnect var src = 'chrome://packagexfly/content/packagebundle.propert ies'; var localeService = Components.classes["@mozilla.org/intl/nslocaleservi ce;1"] .getService(Components.interfaces.nsILocaleService) ; var appLocale = localeService.GetApplicationLocale( ); var stringBundleService = Components.classes["@mozilla.org/intl/stringbundle; 1"] .getService(Components.interfaces.nsIStringBundleSe rvice); bundle = stringBundleService.CreateBundle(src, appLocale); The first step is to get the application locale the language that is currently registered with the chrome service. This is done via the nsILocalService component. The nsIStringBundleService is then initialized and the CreateBundle method is called, returning an instance of nsIStringBundle that provides access to the methods for querying strings. 11.4. Programming and Localization 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. 11.4.1. Naming Conventions The decision of what to call your code internals emerged more than once in this book. In Chapter 8 , 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. 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: id.label id.tooltip id.text id.accesskey id.commandkey Certain XUL widgets can contain multiple localizable resources, including a text label or description, a tooltip, and an accesskey. A button is a prime example: <button id="flyBtn" label="&flyBtn.label;" accesskey="&flyBtn.accesskey;" tooltip="&flyBtn.tooltip;" /> The naming convention is consistent, using the value of the id attribute appended by the name of the UI feature. The attribute and name are delimited by a period. Not only does using this value flag the resource as being associated with a certain widget, but it also permits logical grouping in the DTD: <!ENTITY flyBtn.label "Fly Away"> <!ENTITY flyBtn.accesskey "f"> <!ENTITY flyBtn.tooltip "Click here to take to the air"> Naming string identifiers in bundle files fits less into a pattern like that in DTDs, and in the Mozilla, source files may appear random. If a pattern must be found, you could look at two things: filenames and identifier descriptions. In a filename, the association of a single .properties file is with a logical part of the application. If a string appears in a certain dialog or window, you know where to go to translate the strings or add more strings. Example files in the Mozilla tree worth examining include editor.properties, commonDialogs.properties, and wizardManager.properties. With identifier descriptions, the text used on the identifier describes what the text actually refers to. The goal is to be as descriptive as possible by using as brief text as possible: dontDeleteFiles=Don't Delete Files The descriptor is the same as the value, although in a different format. The opportunity was taken here to be as descriptive as possible. 11.4.2. Breaking Up the Text Under certain circumstances, you may need to pop up your own alert messages as XUL dialogs. Some messages may involve multiple lines of text that need to be put on new lines. There is no natural delimiter that breaks up the text contained within <description> or <label> elements in XUL, so following are a couple of tricks to get around this problem. 11.4.2.1. Method 1: Multiple <description> elements First, create the placeholder in your XUL where the generated elements will be inserted: <vbox id="main-message" flex="1" style="max-width: 40em;"/> <! insert elements here > </vbox> The script in Example 11-5 generates the needed text elements, fills in the text, and appends all the items to the containing box. Example 11-5. Using multiple <description> elements var text = window.arguments[0]; var holder = document.getElementById("main- message"); var lines = text.split("\n"); for (var i = 0; i < lines.length; i++) { var descriptionNode = document.createElement("description"); var linetext = document.createTextNode(lines[i]); descriptionNode.appendChild(linetext); holder.appendChild(descriptionNode); } The text is passed into the window that is used for the message. It presumes that the \n delimiter is used to signify a new line in the text and is split thus. [...]...Then it loops through each line, creating a description element for each line and populating it with a text node with the message inside Then each element is appended to the main container that lives in the XUL file 11.4 .2.2 Method 2: HTML tag For this example, create the XUL placeholder similar to the example in Method... large applications, it can be a big task 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 Appendix B There is also a handy command line utility for Unicode conversion called nsconv, bundled in the Mozilla bin folder in any distribution (If you are unfamiliar with Unicode, the section Section 11.6 .1... descriptionNode.appendChild(breakNode); } holder.appendChild(descriptionNode); This way is similar to the code in Example 11-5, with some notable differences First, there is only one element created outside the loop for each new line In that loop, the break occurs when an HTML element is inserted after a piece of text With both methods, you need to put some sort of width constraint on the window at the level where... Flies" author="Brad Buzzworth"/> The attributes of note here are title and author, both user-defined, because they contain the localizable values that will be used in the binding Example 11-7 Binding with attribute inheritance . binding for the element. 11. 3.2. String Bundle Methods and Properties Defining your bundle in XUL and then creating the file with the values is only. routines that come bundled with Mozilla and are contained in a string resources JavaScript file: strres.js. With this file, creating a bundle is a three-step