Documentation

Class

ResBundle

ResBundle(optionsnullable)

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:

  • locale - The locale of the strings to load. If not specified, the default locale is the the default for the web page or app in which the bundle is being loaded.
  • name - Base name of the resource bundle to load. If not specified the default base name is "resources".
  • type - Name the type of strings this bundle contains. Valid values are "xml", "html", "text", "c", "raw", "ruby", or "template". The default is "text". If the type is "xml" or "html", then XML/HTML entities and tags are not pseudo-translated. During a real translation, HTML character entities are translated to their corresponding characters in a source string before looking that string up in the translations. Also, the characters "<", ">", and "&" are converted to entities again in the output, but characters are left as they are. If the type is "xml", "html", "ruby", or "text" types, then the replacement parameter names are not pseudo-translated as well so that the output can be used for formatting with the IString class. If the type is "c" then all C language style printf replacement parameters (eg. "%s" and "%d") are skipped automatically. This includes iOS/Objective-C/Swift substitution parameters like "%@" or "%1$@". If the type is raw, all characters are pseudo-translated, including replacement parameters as well as XML/HTML tags and entities.
  • lengthen - when pseudo-translating the string, tell whether or not to automatically lengthen the string to simulate "long" languages such as German or French. This is a boolean value. Default is false.
  • missing - what to do when a resource is missing. The choices are:
    • source - return the source string unchanged
    • pseudo - return the pseudo-translated source string, translated to the script of the locale if the mapping is available, or just the default Latin pseudo-translation if not
    • empty - return the empty string
    The default behaviour is the same as before, which is to return the source string unchanged.
  • basePath - look in the given path for the resource bundle files. This can be an absolute path or a relative path that is relative to the application's root. Default if this is not specified is to look in the standard path (ie. in the root of the app).
  • onLoad - a callback function to call when the resources are fully loaded. When the onLoad option is given, this class will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
  • sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
  • loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.

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.

Constructor

# new ResBundle(optionsnullable)

Parameters:
Name Type Attributes Description
options Object <nullable>

Options controlling how the bundle is created

View Source ResBundle.js, line 224

Methods

# containsKey(sourceopt, nullable, keyopt, nullable) → {boolean}

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:
Name Type Attributes Description
source string <optional>
<nullable>

source string to look up
key string <optional>
<nullable>

key to look up

View Source ResBundle.js, line 662

true if this bundle contains a translation for the key, and false otherwise

boolean

# getLocale() → {Locale}

Return the locale of this resource bundle.

View Source ResBundle.js, line 354

the locale of this resource bundle object

Locale

# getName() → {string}

Return the name of this resource bundle. This corresponds to the name option given to the constructor.

View Source ResBundle.js, line 363

name of the the current instance

string

# getResObj() → {Object}

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.

View Source ResBundle.js, line 703

returns the object that is the basis for this resources instance

Object

# getString(source, key, escapeModeopt, nullable) → {IString|Array.<IString>|undefined}

Return a localized string, array, or object. This method can localize individual strings or arrays of strings.

If the source parameter is a string, the translation of that string is looked up and returned. If the source parameter is an array of strings, then the translation of each of the elements of that array is looked up, and an array of translated strings is returned.

If any 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:

  • "html" -- prevents HTML injection by escaping the characters < > and &
  • "xml" -- currently same as "html" mode
  • "js" -- prevents breaking Javascript syntax by backslash escaping all quote and double-quote characters
  • "attribute" -- meant for HTML attribute values. Currently this is the same as "js" escape mode.
  • "default" -- use the type parameter from the constructor as the escape mode as well
  • "none" or undefined -- no escaping at all.

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:
Name Type Attributes Description
source string | Array.<string>=

the source string or strings to translate
key string | Array.<string>=

optional name of the key, if any
escapeMode string <optional>
<nullable>

escape mode, if any

View Source ResBundle.js, line 603

the translation of the given source/key or undefined if the translation is not found and the source is undefined

IString | Array.<IString> | undefined

# getStringJS(source, key, escapeModeopt, nullable) → {string|Array.<string>|undefined}

Return a localized string as an intrinsic Javascript String 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:
Name Type Attributes Description
source string | Array.<string>=

the source string to translate
key string | Array.<string>=

optional name of the key, if any
escapeMode string <optional>
<nullable>

escape mode, if any

View Source ResBundle.js, line 631

the translation of the given source/key or undefined if the translation is not found and the source is undefined

string | Array.<string> | undefined

# getType() → {string}

Return the type of this resource bundle. This corresponds to the type option given to the constructor.

View Source ResBundle.js, line 372

type of the the current instance

string