Class Index | File Index

Classes


Class ResBundle

Create a new resource bundle instance. The resource bundle loads strings appropriate for a particular locale and provides them via the getString method.

The options object may contain any (or none) of the following properties:

The locale option may be given as a locale spec string or as an Locale object. If the locale option is not specified, then strings for the default locale will be loaded.

The name option can be used to put groups of strings together in a single bundle. The strings will then appear together in a JS object in a JS file that can be included before the ilib.

A resource bundle with a particular name is actually a set of bundles that are each specific to a language, a language plus a region, etc. All bundles with the same base name should contain the same set of source strings, but with different translations for the given locale. The user of the bundle does not need to be aware of the locale of the bundle, as long as it contains values for the strings it needs.

Strings in bundles for a particular locale are inherited from parent bundles that are more generic. In general, the hierarchy is as follows (from least locale-specific to most locale-specific):

  1. language
  2. region
  3. language_script
  4. language_region
  5. region_variant
  6. language_script_region
  7. language_region_variant
  8. language_script_region_variant
That is, if the translation for a string does not exist in the current locale, the more-generic parent locale is searched for the string. In the worst case scenario, the string is not found in the base locale's strings. In this case, the missing option guides this class on what to do. If the missing option is "source", then the original source is returned as the translation. If it is "empty", the empty string is returned. If it is "pseudo", then the pseudo-translated string that is appropriate for the default script of the locale is returned.

This allows developers to create code with new or changed strings in it and check in that code without waiting for the translations to be done first. The translated version of the app or web site will still function properly, but will show a spurious untranslated string here and there until the translations are done and also checked in.

The base is whatever language your developers use to code in. For a German web site, strings in the source code may be written in German for example. Often this base is English, as many web sites are coded in English, but that is not required.

The strings can be extracted with the ilib localization tool (which will be shipped at some future time.) Once the strings have been translated, the set of translated files can be generated with the same tool. The output from the tool can be used as input to the ResBundle object. It is up to the web page or app to make sure the JS file that defines the bundle is included before creating the ResBundle instance.

A special locale "zxx-XX" is used as the pseudo-translation locale because zxx means "no linguistic information" in the ISO 639 standard, and the region code XX is defined to be user-defined in the ISO 3166 standard. Pseudo-translation is a locale where the translations are generated on the fly based on the contents of the source string. Characters in the source string are replaced with other characters and returned. Example. If the source string is:

"This is a string"
then the pseudo-translated version might look something like this:
"Ţħïş ïş á şţřïñĝ"

Pseudo-translation can be used to test that your app or web site is translatable before an actual translation has happened. These bugs can then be fixed before the translation starts, avoiding an explosion of bugs later when each language's tester registers the same bug complaining that the same string is not translated. When pseudo-localizing with the Latin script, this allows the strings to be readable in the UI in the source language (if somewhat funky-looking), so that a tester can easily verify that the string is properly externalized and loaded from a resource bundle without the need to be able to read a foreign language.

If one of a list of script tags is given in the pseudo-locale specifier, then the pseudo-localization can map characters to very rough transliterations of characters in the given script. For example, zxx-Hebr-XX maps strings to Hebrew characters, which can be used to test your UI in a right-to-left language to catch bidi bugs before a translation is done. Currently, the list of target scripts includes Hebrew (Hebr), Chinese Simplified Han (Hans), and Cyrillic (Cyrl) with more to be added later. If no script is explicitly specified in the locale spec, or if the script is not supported, then the default mapping maps Latin base characters to accented versions of those Latin characters as in the example above. When the "lengthen" property is set to true in the options, the pseudotranslation code will add digits to the end of the string to simulate the lengthening that occurs when translating to other languages. The above example will come out like this:

"Ţħïş ïş á şţřïñĝ76543210"
The string is lengthened according to the length of the source string. If the source string is less than 20 characters long, the string is lengthened by 50%. If the source string is 20-40 characters long, the string is lengthened by 33%. If te string is greater than 40 characters long, the string is lengthened by 20%.

The pseudotranslation always ends a string with the digit "0". If you do not see the digit "0" in the UI for your app, you know that truncation has occurred, and the number you see at the end of the string tells you how many characters were truncated.


Defined in: ilib-full-dyn.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
ResBundle(options)
Method Summary
Method Attributes Method Name and Description
 
containsKey(source, key)
Return true if the current bundle contains a translation for the given key and source.
 
Return the locale of this resource bundle.
 
Return the name of this resource bundle.
 
Return the merged resources as an entire object.
 
getString(source, key, escapeMode)
Return a localized string.
 
getStringJS(source, key, escapeMode)
Return a localized string as a Javascript object.
 
Return the type of this resource bundle.
Class Detail
ResBundle(options)
Parameters:
{?Object} options
Options controlling how the bundle is created
Method Detail
{boolean} containsKey(source, key)
Return true if the current bundle contains a translation for the given key and source. The getString method will always return a string for any given key and source combination, so it cannot be used to tell if a translation exists. Either one or both of the source and key must be specified. If both are not specified, this method will return false.
Parameters:
{?string=} source
source string to look up
{?string=} key
key to look up
Returns:
{boolean} true if this bundle contains a translation for the key, and false otherwise

{Locale} getLocale()
Return the locale of this resource bundle.
Returns:
{Locale} the locale of this resource bundle object

{string} getName()
Return the name of this resource bundle. This corresponds to the name option given to the constructor.
Returns:
{string} name of the the current instance

{Object} getResObj()
Return the merged resources as an entire object. When loading resources for a locale that are not just a set of translated strings, but instead an entire structured javascript object, you can gain access to that object via this call. This method will ensure that all the of the parts of the object are correct for the locale.

For pre-assembled data, it starts by loading ilib.data[name], where name is the base name for this set of resources. Then, it successively merges objects in the base data using progressively more locale-specific data. It loads it in this order from ilib.data:

  1. language
  2. region
  3. language_script
  4. language_region
  5. region_variant
  6. language_script_region
  7. language_region_variant
  8. language_script_region_variant
For dynamically loaded data, the code attempts to load the same sequence as above, but with slash path separators instead of underscores.

Loading the resources this way allows the program to share resources between all locales that share a common language, region, or script. As a general rule-of-thumb, resources should be as generic as possible in order to cover as many locales as possible.

Returns:
{Object} returns the object that is the basis for this resources instance

{IString|undefined} getString(source, key, escapeMode)
Return a localized string. If the string is not found in the loaded set of resources, the original source string is returned. If the key is not given, then the source string itself is used as the key. In the case where the source string is used as the key, the whitespace is compressed down to 1 space each, and the whitespace at the beginning and end of the string is trimmed.

The escape mode specifies what type of output you are escaping the returned string for. Modes are similar to the types:

The type parameter of the constructor specifies what type of strings this bundle is operating upon. This allows pseudo-translation and automatic key generation to happen properly by telling this class how to parse the string. The escape mode for this method is different in that it specifies how this string will be used in the calling code and therefore how to escape it properly.

For example, a section of Javascript code may be constructing an HTML snippet in a string to add to the web page. In this case, the type parameter in the constructor should be "html" so that the source string can be parsed properly, but the escape mode should be "js" so that the output string can be used in Javascript without causing syntax errors.

Parameters:
{?string=} source
the source string to translate
{?string=} key
optional name of the key, if any
{?string=} escapeMode
escape mode, if any
Returns:
{IString|undefined} the translation of the given source/key or undefined if the translation is not found and the source is undefined

{string|undefined} getStringJS(source, key, escapeMode)
Return a localized string as a Javascript object. This does the same thing as the getString() method, but it returns a regular Javascript string instead of and IString instance. This means it cannot be formatted with the format() method without being wrapped in an IString instance first.
Parameters:
{?string=} source
the source string to translate
{?string=} key
optional name of the key, if any
{?string=} escapeMode
escape mode, if any
Returns:
{string|undefined} the translation of the given source/key or undefined if the translation is not found and the source is undefined

{string} getType()
Return the type of this resource bundle. This corresponds to the type option given to the constructor.
Returns:
{string} type of the the current instance

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Jun 14 2017 00:48:37 GMT-0700 (PDT)