JSDoc: Class: Gettext

new Gettext() → {iJS.Gettext}

Javascript implemenation of GNU Gettext API.

Source:

i_gettext.js, line 111

Returns:

Type: iJS.Gettext

Example

//create new instance
var igt = new iJS.Gettext() ;
//set the locale in which the messages have to be translated.
igt.setlocale("fr_FR.utf8") ; // local can also be *fr_FR* or *fr*.
//Supposing that most users now have browser that support Ajax;
//also add or register a domain where to get the messages data.
igt.bindtextdomain("mydomain", "./path_to_locale", "po") ; //"po" can also be "json" or by default "mo".
//Always do this after a `setlocale` or a `bindtextdomain` call.
igt.try_load_lang() ; //will load and parse messages data from the setting catalog.
//Then print your messages
alert( igt.gettext("Hello world!") ) ;

//Like with GNU gettext, your domain path have to be
// path_to_locale/LC_MESSAGES/fr_FR.utf8/mydomain.po
// if "fr_FR.utf8" is not found, "fr_FR" or "fr" will be use for replacement.
//This is just an overview. See tutoriels for more.

//Optimum caching way to add domain is to use *<script>* tag to load it via *iJS.Gettext*’s json like file.
//just do this to add or register a domain where to get the messages data.
igt.locale_data = external_locale_data ;
igt.bindtextdomain("json-domain") ; //domain can be any domain in *external_locale_date*
/* Supposing that this declaration have be done:`<SCRIPT language="javascript" src="path_to/gettext_json_file"></SCRIPT>`
 * and the gettext_json_file content structurate object like:
 external_locale_data = {
        "json-domain" : {
            // po header fields
            "" : {
                "plural-forms" : "...",
                "lang" : "en",
                },
            // all the msgid strings and translations
            "msgid" : [ "msgid_plural", "translation", "plural_translation" ],
            "msgctxt\004msgid" : [ null, "msgstr" ],
         },
     "AnotherDomain" : {
         },
    };

Classes

Strargs

Members

(static, constant) Magic :Number

constant to check the endianness of the input file.

Type:

Number

Source:

i_gettext.js, line 797

Methods

bindtextdomain(domain, localePath, dtype)

Add or register a domain where to get the messages data

Parameters:

Name	Type	Description
`domain`	string	The Gettext domain, not www.whatev.com. If the .po file was "myapp.po", this would be "myapp".
`localePath`	string	Path to the locale directory where to find the domain. egg: "./locale" in which we can have ".locale/LC_MESSAGES/fr_FR.utf8/domain.po". If omitted, it will mean that domain will be considered in a json Object or file. See tutorials for more explanation.
`dtype`	string	Type of domain file. Supported files are "po", "json" and "mo"(support is planned). If omitted, the default value will be "mo".

Source:

i_gettext.js, line 202

dcgettext(domain, msgid, category) → {String}

Like `dgettext()` but retrieves the message from the specified **CATEGORY** instead of the default category "LC_MESSAGES".
NOTE: the categories are really useless in javascript context. This is here for GNU Gettext API compatibility. In practice, you'll never need to use this. This applies to all the calls including the **CATEGORY**.

Parameters:

Name	Type	Description
`domain`	String	Domain where translation can be found.
`msgid`	String	Message to translate
`category`	String	(for now is will always be "LC_MESSAGES")

Source:

i_gettext.js, line 1084

Returns:

translated text or the *msgid* if not found

Type: String

dcngettext(domain, msgid, msgid_plural, n, category) → {String}

Like `dngettext()` but retrieves the translation from the specified category, instead of the default category **LC_MESSAGES**.

Parameters:

Name	Type	Description
`domain`	String	Domain where translation can be found.
`msgid`	String	Message to translate
`msgid_plural`	String	Plural form of text to translate
`n`	Number	Counting number
`category`	String	(for now is will always be "LC_MESSAGES")

Source:

i_gettext.js, line 1150

Returns:

translated text or the *msgid* if not found

Type: String

dcnpgettext(domain, msgctxt, msgid, msgid_plural, n, category) → {String}

Like `dnpgettext()` but retrieves the translation from the specified category, instead of the default category **LC_MESSAGES**.

Parameters:

Name	Type	Description
`domain`	String	Domain where translation can be found.
`msgctxt`	String	Context of text
`msgid`	String	Message to translate
`msgid_plural`	String	Plural form of text to translate
`n`	Number
`category`	String	(for now is will always be "LC_MESSAGES")

Source:

i_gettext.js, line 1264

Returns:

translated text or the *msgid* if not found

Type: String

dcpgettext(domain, msgctxt, msgid, category) → {String}

Like `dpgettext()` but retrieves the message from the specified **category** instead of the default category **LC_MESSAGES**.

Parameters:

Name	Type	Description
`domain`	String	Domain where translation can be found.
`msgctxt`	String	Context of text
`msgid`	String	Message to translate
`category`	String	(for now is will always be "LC_MESSAGES")

Source:

i_gettext.js, line 1208

Returns:

translated text or the *msgid* if not found

Type: String

dgettext(domain, msgid) → {String}

Like `gettext()`, but retrieves the message for the specified **TEXTDOMAIN** instead of the default domain.

Parameters:

Name	Type	Description
`domain`	String	Domain where translation can be found.
`msgid`	String	Message to translate

Source:

i_gettext.js, line 1063

Returns:

translated text or the *msgid* if not found

Type: String

dngettext(domain, msgid, msgid_plural, n) → {String}

Like `ngettext()` but retrieves the translation from the specified textdomain instead of the default domain.

Parameters:

Name	Type	Description
`domain`	String	Domain where translation can be found.
`msgid`	String	Message to translate
`msgid_plural`	String	Plural form of text to translate
`n`	Number	Counting number

Source:

i_gettext.js, line 1132

Returns:

translated text or the *msgid* if not found

Type: String

dnpgettext(domain, msgctxt, msgid, msgid_plural, n) → {String}

Like `npgettext()` but retrieves the translation from the specified textdomain instead of the default domain.

Parameters:

Name	Type	Description
`domain`	String	Domain where translation can be found.
`msgctxt`	String	Context of text
`msgid`	String	Message to translate
`msgid_plural`	String	Plural form of text to translate
`n`	Number	Counting number

Source:

i_gettext.js, line 1244

Returns:

translated text or the *msgid* if not found

Type: String

dpgettext(domain, msgctxt, msgid) → {String}

Like `pgettext()`, but retrieves the message for the specified **domain** instead of the default domain.

Parameters:

Name	Type	Description
`domain`	String	Domain where translation can be found.
`msgctxt`	String	Context of text
`msgid`	String	Message to translate

Source:

i_gettext.js, line 1190

Returns:

translated text or the *msgid* if not found

Type: String

gettext(msgid) → {String}

Returns the translation for **msgid**.
If translation can’t be found, the unmodified **msgid** is returned.

Parameters:

Name	Type	Description
`msgid`	String	Message to translate

Source:

i_gettext.js, line 1045

Returns:

translated text or the *msgid* if not found

Type: String

ngettext(msgid, msgid_plural, n) → {String}

Retrieves the correct translation for **count** items.

Parameters:

Name	Type	Description
`msgid`	String	Message to translate
`msgid_plural`	String	Plural form of text to translate
`n`	Number	Counting number

Source:

i_gettext.js, line 1115

Returns:

translated text or the *msgid* if not found

Type: String

Example

//In legacy software you will often find something like:
alert( count + " file(s) deleted.\n" );
//Before ngettext() was introduced, one of best practice for internationalized programs was:
    if (count == 1)
        alert( iJS._("One file deleted.\n") );
    else ...

   //This is a nuisance for the programmer and often still not sufficient for an adequate translation.  
   //Many languages have completely different ideas on numerals.  Some (French, Italian, ...) treat 0 and 1 alike,
   //others make no distinction at all (Japanese, Korean, Chinese, ...), others have two or more plural forms (Russian, 
   //Latvian, Czech, Polish, ...).  The solution is:

    alert( iJS.i18n.ngettext("One file deleted.\n", "%d files deleted.\n", count) );

npgettext(msgctxt, msgid, msgid_plural, n) → {String}

Like `ngettext()` with the addition of context as in `pgettext()`.
In English, or if no translation can be found, the second argument *msgid* is picked if *n* is one, the third one otherwise.

Parameters:

Name	Type	Description
`msgctxt`	String	Context of text
`msgid`	String	Message to translate
`msgid_plural`	String	Plural form of text to translate
`n`	Number	Counting number

Source:

i_gettext.js, line 1227

Returns:

translated text or the *msgid* if not found

Type: String

pgettext(msgctxt, msgid) → {String}

Returns the translation of **msgid**, given the context of **msgctxt**.
Both items are used as a unique key into the message catalog. This allows the translator to have two entries for words that may translate to different foreign words based on their context.

Parameters:

Name	Type	Description
`msgctxt`	String	context of text
`msgid`	String	Message to translate

Source:

i_gettext.js, line 1173

Returns:

translated text or the *msgid* if not found

Type: String

Example

// The word "View" may be a noun or a verb, which may be
//used in a menu as File->View or View->Source.

    alert( iJS.i18n.pgettext( "Verb: To View", "View" ) );
    alert( iJS.i18n.pgettext( "Noun: A View", "View"  ) );
// The above will both lookup different entries in the message catalog.

setlocale(locale)

Set the locale in which the messages have to be translated.

Parameters:

Name	Type	Description
`locale`	String	egg: "en", "en_US.utf8", "en_GB" ...

Source:

i_gettext.js, line 166

strargs(str, args) → {String}

instance method wrapper of strargs

Parameters:

Name	Type	Description
`str`	String	a string that potentially contains formatting characters
`args`	Array	an array of positional replacement values

Source:

i_gettext.js, line 1434

Returns:

The formatted text.

Type: String

textdomain(domain) → {string}

Set domain for future `gettext()` calls.
If the given domain is not NULL, the current message domain is set to it; else the function returns the current message domain.
A message domain is a set of translatable msgid messages. Usually, every software package has its own message domain. The domain name is used to determine the message catalog where a translation is looked up; it must be a non-empty string.

Parameters:

Name	Type	Description
`domain`	string	message domain to set as current.

Source:

i_gettext.js, line 1031

Returns:

current message domain.

Type: string

try_load_lang()

Load and parse all the messages data from domain in the domain’s registry. Data are load depending of the setting catalog or developer’s defined json’d portable object. Parsed data are save in a internal json structure, to make them easily accessible, depending of the current domain. This method have to be always call after a `setlocale` and `bindtextdomain` call.

Source:

i_gettext.js, line 280