"Fossies" - the Fresh Open Source Software Archive

Member "icinga-web-1.14.1/lib/jsgettext/README" (19 Dec 2017, 20889 Bytes) of package /linux/misc/old/icinga-web-1.14.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 NAME
    2     Javascript Gettext - Javascript implemenation of GNU Gettext API.
    3 
    4 SYNOPSIS
    5      // //////////////////////////////////////////////////////////
    6      // Optimum caching way
    7      <script language="javascript" src="/path/LC_MESSAGES/myDomain.json"></script>
    8      <script language="javascript" src="/path/Gettext.js'></script>
    9 
   10      // assuming myDomain.json defines variable json_locale_data
   11      var params = {  "domain" : "myDomain",
   12                      "locale_data" : json_locale_data
   13                   };
   14      var gt = new Gettext(params);
   15      // create a shortcut if you'd like
   16      function _ (msgid) { return gt.gettext(msgid); }
   17      alert(_("some string"));
   18      // or use fully named method
   19      alert(gt.gettext("some string"));
   20      // change to use a different "domain"
   21      gt.textdomain("anotherDomain");
   22      alert(gt.gettext("some string"));
   23 
   24      // //////////////////////////////////////////////////////////
   25      // The other way to load the language lookup is a "link" tag
   26      // Downside is that not all browsers cache XMLHttpRequests the
   27      // same way, so caching of the language data isn't guarenteed
   28      // across page loads.
   29      // Upside is that it's easy to specify multiple files
   30      <link rel="gettext" href="/path/LC_MESSAGES/myDomain.json" />
   31      <script language="javascript" src="/path/Gettext.js'></script>
   32 
   33      var gt = new Gettext({ "domain" : "myDomain" });
   34      // rest is the same
   35 
   36      // //////////////////////////////////////////////////////////
   37      // The reson the shortcuts aren't exported by default is because they'd be
   38      // glued to the single domain you created. So, if you're adding i18n support
   39      // to some js library, you should use it as so:
   40 
   41      if (typeof(MyNamespace) == 'undefined') MyNamespace = {};
   42      MyNamespace.MyClass = function () {
   43          var gtParms = { "domain" : 'MyNamespace_MyClass' };
   44          this.gt = new Gettext(gtParams);
   45          return this;
   46      };
   47      MyNamespace.MyClass.prototype._ = function (msgid) {
   48          return this.gt.gettext(msgid);
   49      };
   50      MyNamespace.MyClass.prototype.something = function () {
   51          var myString = this._("this will get translated");
   52      };
   53 
   54      // //////////////////////////////////////////////////////////
   55      // Adding the shortcuts to a global scope is easier. If that's
   56      // ok in your app, this is certainly easier.
   57      var myGettext = new Gettext({ 'domain' : 'myDomain' });
   58      function _ (msgid) {
   59          return myGettext.gettext(msgid);
   60      }
   61      alert( _("text") );
   62 
   63      // //////////////////////////////////////////////////////////
   64      // Data structure of the json data
   65      // NOTE: if you're loading via the <script> tag, you can only
   66      // load one file, but it can contain multiple domains.
   67      var json_locale_data = {
   68          "MyDomain" : {
   69              "" : {
   70                  "header_key" : "header value",
   71                  "header_key" : "header value",
   72              "msgid" : [ "msgid_plural", "msgstr", "msgstr_plural", "msgstr_pluralN" ],
   73              "msgctxt\004msgid" : [ null, "msgstr" ],
   74              },
   75          "AnotherDomain" : {
   76              },
   77          }
   78 
   79 DESCRIPTION
   80     This is a javascript implementation of GNU Gettext, providing
   81     internationalization support for javascript. It differs from existing
   82     javascript implementations in that it will support all current Gettext
   83     features (ex. plural and context support), and will also support loading
   84     language catalogs from .mo, .po, or preprocessed json files (converter
   85     included).
   86 
   87     The locale initialization differs from that of GNU Gettext / POSIX.
   88     Rather than setting the category, domain, and paths, and letting the
   89     libs find the right file, you must explicitly load the file at some
   90     point. The "domain" will still be honored. Future versions may be
   91     expanded to include support for set_locale like features.
   92 
   93 INSTALL
   94     To install this module, simply copy the file lib/Gettext.js to a web
   95     accessable location, and reference it from your application.
   96 
   97 CONFIGURATION
   98     Configure in one of two ways:
   99 
  100     1. Optimal. Load language definition from statically defined json data.
  101             <script language="javascript" src="/path/locale/domain.json"></script>
  102 
  103             // in domain.json
  104             json_locale_data = {
  105                 "mydomain" : {
  106                     // po header fields
  107                     "" : {
  108                         "plural-forms" : "...",
  109                         "lang" : "en",
  110                         },
  111                     // all the msgid strings and translations
  112                     "msgid" : [ "msgid_plural", "translation", "plural_translation" ],
  113                 },
  114             };
  115             // please see the included bin/po2json script for the details on this format
  116 
  117         This method also allows you to use unsupported file formats, so long
  118         as you can parse them into the above format.
  119 
  120     2. Use AJAX to load language file.
  121         Use XMLHttpRequest (actually, SJAX - syncronous) to load an external
  122         resource.
  123 
  124         Supported external formats are:
  125 
  126         * Javascript Object Notation (.json)
  127             (see bin/po2json)
  128 
  129                 type=application/json
  130 
  131         * Uniforum Portable Object (.po)
  132             (see GNU Gettext's xgettext)
  133 
  134                 type=application/x-po
  135 
  136         * Machine Object (compiled .po) (.mo)
  137             NOTE: .mo format isn't actually supported just yet, but support
  138             is planned.
  139 
  140             (see GNU Gettext's msgfmt)
  141 
  142                 type=application/x-mo
  143 
  144 METHODS
  145     The following methods are implemented:
  146 
  147       new Gettext(args)
  148       textdomain  (domain)
  149       gettext     (msgid)
  150       dgettext    (domainname, msgid)
  151       dcgettext   (domainname, msgid, LC_MESSAGES)
  152       ngettext    (msgid, msgid_plural, count)
  153       dngettext   (domainname, msgid, msgid_plural, count)
  154       dcngettext  (domainname, msgid, msgid_plural, count, LC_MESSAGES)
  155       pgettext    (msgctxt, msgid)
  156       dpgettext   (domainname, msgctxt, msgid)
  157       dcpgettext  (domainname, msgctxt, msgid, LC_MESSAGES)
  158       npgettext   (msgctxt, msgid, msgid_plural, count)
  159       dnpgettext  (domainname, msgctxt, msgid, msgid_plural, count)
  160       dcnpgettext (domainname, msgctxt, msgid, msgid_plural, count, LC_MESSAGES)
  161       strargs     (string, args_array)
  162 
  163   new Gettext (args)
  164     Several methods of loading locale data are included. You may specify a
  165     plugin or alternative method of loading data by passing the data in as
  166     the "locale_data" option. For example:
  167 
  168         var get_locale_data = function () {
  169             // plugin does whatever to populate locale_data
  170             return locale_data;
  171         };
  172         var gt = new Gettext( 'domain' : 'messages',
  173                               'locale_data' : get_locale_data() );
  174 
  175     The above can also be used if locale data is specified in a statically
  176     included <SCRIPT> tag. Just specify the variable name in the call to
  177     new. Ex:
  178 
  179         var gt = new Gettext( 'domain' : 'messages',
  180                               'locale_data' : json_locale_data_variable );
  181 
  182     Finally, you may load the locale data by referencing it in a <LINK> tag.
  183     Simply exclude the 'locale_data' option, and all <LINK rel="gettext"
  184     ...> items will be tried. The <LINK> should be specified as:
  185 
  186         <link rel="gettext" type="application/json" href="/path/to/file.json">
  187         <link rel="gettext" type="text/javascript"  href="/path/to/file.json">
  188         <link rel="gettext" type="application/x-po" href="/path/to/file.po">
  189         <link rel="gettext" type="application/x-mo" href="/path/to/file.mo">
  190 
  191     args:
  192 
  193     domain
  194         The Gettext domain, not www.whatev.com. It's usually your
  195         applications basename. If the .po file was "myapp.po", this would be
  196         "myapp".
  197 
  198     locale_data
  199         Raw locale data (in json structure). If specified, from_link data
  200         will be ignored.
  201 
  202   textdomain( domain )
  203     Set domain for future gettext() calls
  204 
  205     A message domain is a set of translatable msgid messages. Usually, every
  206     software package has its own message domain. The domain name is used to
  207     determine the message catalog where a translation is looked up; it must
  208     be a non-empty string.
  209 
  210     The current message domain is used by the gettext, ngettext, pgettext,
  211     npgettext functions, and by the dgettext, dcgettext, dngettext,
  212     dcngettext, dpgettext, dcpgettext, dnpgettext and dcnpgettext functions
  213     when called with a NULL domainname argument.
  214 
  215     If domainname is not NULL, the current message domain is set to
  216     domainname.
  217 
  218     If domainname is undefined, null, or empty string, the function returns
  219     the current message domain.
  220 
  221     If successful, the textdomain function returns the current message
  222     domain, after possibly changing it. (ie. if you set a new domain, the
  223     value returned will NOT be the previous domain).
  224 
  225   gettext( MSGID )
  226     Returns the translation for MSGID. Example:
  227 
  228         alert( gt.gettext("Hello World!\n") );
  229 
  230     If no translation can be found, the unmodified MSGID is returned, i. e.
  231     the function can *never* fail, and will *never* mess up your original
  232     message.
  233 
  234     One common mistake is to interpolate a variable into the string like
  235     this:
  236 
  237       var translated = gt.gettext("Hello " + full_name);
  238 
  239     The interpolation will happen before it's passed to gettext, and it's
  240     unlikely you'll have a translation for every "Hello Tom" and "Hello
  241     Dick" and "Hellow Harry" that may arise.
  242 
  243     Use "strargs()" (see below) to solve this problem:
  244 
  245       var translated = Gettext.strargs( gt.gettext("Hello %1"), [full_name] );
  246 
  247     This is espeically useful when multiple replacements are needed, as they
  248     may not appear in the same order within the translation. As an English
  249     to French example:
  250 
  251       Expected result: "This is the red ball"
  252       English: "This is the %1 %2"
  253       French:  "C'est le %2 %1"
  254       Code: Gettext.strargs( gt.gettext("This is the %1 %2"), ["red", "ball"] );
  255 
  256     (The example is stupid because neither color nor thing will get
  257     translated here ...).
  258 
  259   dgettext( TEXTDOMAIN, MSGID )
  260     Like gettext(), but retrieves the message for the specified TEXTDOMAIN
  261     instead of the default domain. In case you wonder what a textdomain is,
  262     see above section on the textdomain() call.
  263 
  264   dcgettext( TEXTDOMAIN, MSGID, CATEGORY )
  265     Like dgettext() but retrieves the message from the specified CATEGORY
  266     instead of the default category "LC_MESSAGES".
  267 
  268     NOTE: the categories are really useless in javascript context. This is
  269     here for GNU Gettext API compatability. In practice, you'll never need
  270     to use this. This applies to all the calls including the CATEGORY.
  271 
  272   ngettext( MSGID, MSGID_PLURAL, COUNT )
  273     Retrieves the correct translation for COUNT items. In legacy software
  274     you will often find something like:
  275 
  276         alert( count + " file(s) deleted.\n" );
  277 
  278     or
  279 
  280         printf(count + " file%s deleted.\n", $count == 1 ? '' : 's');
  281 
  282     *NOTE: javascript lacks a builtin printf, so the above isn't a working
  283     example*
  284 
  285     The first example looks awkward, the second will only work in English
  286     and languages with similar plural rules. Before ngettext() was
  287     introduced, the best practice for internationalized programs was:
  288 
  289         if (count == 1) {
  290             alert( gettext("One file deleted.\n") );
  291         } else {
  292             printf( gettext("%d files deleted.\n"), count );
  293         }
  294 
  295     This is a nuisance for the programmer and often still not sufficient for
  296     an adequate translation. Many languages have completely different ideas
  297     on numerals. Some (French, Italian, ...) treat 0 and 1 alike, others
  298     make no distinction at all (Japanese, Korean, Chinese, ...), others have
  299     two or more plural forms (Russian, Latvian, Czech, Polish, ...). The
  300     solution is:
  301 
  302         printf( ngettext("One file deleted.\n",
  303                          "%d files deleted.\n",
  304                          count), // argument to ngettext!
  305                 count);          // argument to printf!
  306 
  307     In English, or if no translation can be found, the first argument
  308     (MSGID) is picked if "count" is one, the second one otherwise. For other
  309     languages, the correct plural form (of 1, 2, 3, 4, ...) is automatically
  310     picked, too. You don't have to know anything about the plural rules in
  311     the target language, ngettext() will take care of that.
  312 
  313     This is most of the time sufficient but you will have to prove your
  314     creativity in cases like
  315 
  316         "%d file(s) deleted, and %d file(s) created.\n"
  317 
  318     That said, javascript lacks "printf()" support. Supplied with Gettext.js
  319     is the "strargs()" method, which can be used for these cases:
  320 
  321         Gettext.strargs( gt.ngettext( "One file deleted.\n",
  322                                       "%d files deleted.\n",
  323                                       count), // argument to ngettext!
  324                          count); // argument to strargs!
  325 
  326     NOTE: the variable replacement isn't done for you, so you must do it
  327     yourself as in the above.
  328 
  329   dngettext( TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT )
  330     Like ngettext() but retrieves the translation from the specified
  331     textdomain instead of the default domain.
  332 
  333   dcngettext( TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT, CATEGORY )
  334     Like dngettext() but retrieves the translation from the specified
  335     category, instead of the default category "LC_MESSAGES".
  336 
  337   pgettext( MSGCTXT, MSGID )
  338     Returns the translation of MSGID, given the context of MSGCTXT.
  339 
  340     Both items are used as a unique key into the message catalog.
  341 
  342     This allows the translator to have two entries for words that may
  343     translate to different foreign words based on their context. For
  344     example, the word "View" may be a noun or a verb, which may be used in a
  345     menu as File->View or View->Source.
  346 
  347         alert( pgettext( "Verb: To View", "View" ) );
  348         alert( pgettext( "Noun: A View", "View"  ) );
  349 
  350     The above will both lookup different entries in the message catalog.
  351 
  352     In English, or if no translation can be found, the second argument
  353     (MSGID) is returned.
  354 
  355   dpgettext( TEXTDOMAIN, MSGCTXT, MSGID )
  356     Like pgettext(), but retrieves the message for the specified TEXTDOMAIN
  357     instead of the default domain.
  358 
  359   dcpgettext( TEXTDOMAIN, MSGCTXT, MSGID, CATEGORY )
  360     Like dpgettext() but retrieves the message from the specified CATEGORY
  361     instead of the default category "LC_MESSAGES".
  362 
  363   npgettext( MSGCTXT, MSGID, MSGID_PLURAL, COUNT )
  364     Like ngettext() with the addition of context as in pgettext().
  365 
  366     In English, or if no translation can be found, the second argument
  367     (MSGID) is picked if COUNT is one, the third one otherwise.
  368 
  369   dnpgettext( TEXTDOMAIN, MSGCTXT, MSGID, MSGID_PLURAL, COUNT )
  370     Like npgettext() but retrieves the translation from the specified
  371     textdomain instead of the default domain.
  372 
  373   dcnpgettext( TEXTDOMAIN, MSGCTXT, MSGID, MSGID_PLURAL, COUNT, CATEGORY )
  374     Like dnpgettext() but retrieves the translation from the specified
  375     category, instead of the default category "LC_MESSAGES".
  376 
  377   strargs (string, argument_array)
  378       string : a string that potentially contains formatting characters.
  379       argument_array : an array of positional replacement values
  380 
  381     This is a utility method to provide some way to support positional
  382     parameters within a string, as javascript lacks a printf() method.
  383 
  384     The format is similar to printf(), but greatly simplified (ie. fewer
  385     features).
  386 
  387     Any percent signs followed by numbers are replaced with the
  388     corrosponding item from the argument_array.
  389 
  390     Example:
  391 
  392         var string = "%2 roses are red, %1 violets are blue";
  393         var args   = new Array("10", "15");
  394         var result = Gettext.strargs(string, args);
  395         // result is "15 roses are red, 10 violets are blue"
  396 
  397     The format numbers are 1 based, so the first itme is %1.
  398 
  399     A lone percent sign may be escaped by preceeding it with another percent
  400     sign.
  401 
  402     A percent sign followed by anything other than a number or another
  403     percent sign will be passed through as is.
  404 
  405     Some more examples should clear up any abmiguity. The following were
  406     called with the orig string, and the array as Array("[one]", "[two]") :
  407 
  408       orig string "blah" becomes "blah"
  409       orig string "" becomes ""
  410       orig string "%%" becomes "%"
  411       orig string "%%%" becomes "%%"
  412       orig string "%%%%" becomes "%%"
  413       orig string "%%%%%" becomes "%%%"
  414       orig string "tom%%dick" becomes "tom%dick"
  415       orig string "thing%1bob" becomes "thing[one]bob"
  416       orig string "thing%1%2bob" becomes "thing[one][two]bob"
  417       orig string "thing%1asdf%2asdf" becomes "thing[one]asdf[two]asdf"
  418       orig string "%1%2%3" becomes "[one][two]"
  419       orig string "tom%1%%2%aDick" becomes "tom[one]%2%aDick"
  420 
  421     This is especially useful when using plurals, as the string will nearly
  422     always contain the number.
  423 
  424     It's also useful in translated strings where the translator may have
  425     needed to move the position of the parameters.
  426 
  427     For example:
  428 
  429       var count = 14;
  430       Gettext.strargs( gt.ngettext('one banana', '%1 bananas', count), [count] );
  431 
  432     NOTE: this may be called as an instance method, or as a class method.
  433 
  434       // instance method:
  435       var gt = new Gettext(params);
  436       gt.strargs(string, args);
  437 
  438       // class method:
  439       Gettext.strargs(string, args);
  440 
  441 NOTES
  442     These are some notes on the internals
  443 
  444     LOCALE CACHING
  445         Loaded locale data is currently cached class-wide. This means that
  446         if two scripts are both using Gettext.js, and both share the same
  447         gettext domain, that domain will only be loaded once. This will
  448         allow you to grab a new object many times from different places,
  449         utilize the same domain, and share a single translation file. The
  450         downside is that a domain won't be RE-loaded if a new object is
  451         instantiated on a domain that had already been instantiated.
  452 
  453 BUGS / TODO
  454     error handling
  455         Currently, there are several places that throw errors. In GNU
  456         Gettext, there are no fatal errors, which allows text to still be
  457         displayed regardless of how broken the environment becomes. We
  458         should evaluate and determine where we want to stand on that issue.
  459 
  460     syncronous only support (no ajax support)
  461         Currently, fetching language data is done purely syncronous, which
  462         means the page will halt while those files are fetched/loaded.
  463 
  464         This is often what you want, as then following translation requests
  465         will actually be translated. However, if all your calls are done
  466         dynamically (ie. error handling only or something), loading in the
  467         background may be more adventagous.
  468 
  469         It's still recommended to use the statically defined <script ...>
  470         method, which should have the same delay, but it will cache the
  471         result.
  472 
  473     domain support
  474         domain support while using shortcut methods like "_('string')" or
  475         "i18n('string')".
  476 
  477         Under normal apps, the domain is usually set globally to the app,
  478         and a single language file is used. Under javascript, you may have
  479         multiple libraries or applications needing translation support, but
  480         the namespace is essentially global.
  481 
  482         It's recommended that your app initialize it's own shortcut with
  483         it's own domain. (See examples/wrapper/i18n.js for an example.)
  484 
  485         Basically, you'll want to accomplish something like this:
  486 
  487             // in some other .js file that needs i18n
  488             this.i18nObj = new i18n;
  489             this.i18n = this.i18nObj.init('domain');
  490             // do translation
  491             alert( this.i18n("string") );
  492 
  493         If you use this raw Gettext object, then this is all handled for
  494         you, as you have your own object then, and will be calling
  495         "myGettextObject.gettext('string')" and such.
  496 
  497     encoding
  498         May want to add encoding/reencoding stuff. See GNU iconv, or the
  499         perl module Locale::Recode from libintl-perl.
  500 
  501 COMPATABILITY
  502     This has been tested on the following browsers. It may work on others,
  503     but these are all those to which I have access.
  504 
  505         FF1.5, FF2, FF3, IE6, IE7, Opera9, Opera10, Safari3.1, Chrome
  506 
  507         *FF = Firefox
  508         *IE = Internet Explorer
  509 
  510 REQUIRES
  511     bin/po2json requires perl, and the perl modules Locale::PO and JSON.
  512 
  513 SEE ALSO
  514     bin/po2json (included), examples/normal/index.html,
  515     examples/wrapper/i18n.html, examples/wrapper/i18n.js,
  516     Locale::gettext_pp(3pm), POSIX(3pm), gettext(1), gettext(3)
  517 
  518 AUTHOR
  519     Copyright (C) 2008, Joshua I. Miller <unrtst@cpan.org>, all rights
  520     reserved. See the source code for details.
  521