koha-tmpl/opac-tmpl/bootstrap/js/Gettext.js

   1 /*
   2 Pure Javascript implementation of Uniforum message translation.
   3 Copyright (C) 2008 Joshua I. Miller <unrtst@cpan.org>, all rights reserved
   4
   5 This program is free software; you can redistribute it and/or modify it
   6 under the terms of the GNU Library General Public License as published
   7 by the Free Software Foundation; either version 2, or (at your option)
   8 any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 Library General Public License for more details.
  14
  15 You should have received a copy of the GNU Library General Public
  16 License along with this program; if not, write to the Free Software
  17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  18 USA.
  19
  20 =head1 NAME
  21
  22 Javascript Gettext - Javascript implemenation of GNU Gettext API.
  23
  24 =head1 SYNOPSIS
  25
  26  // //////////////////////////////////////////////////////////
  27  // Optimum caching way
  28  <script language="javascript" src="/path/LC_MESSAGES/myDomain.json"></script>
  29  <script language="javascript" src="/path/Gettext.js'></script>
  30
  31  // assuming myDomain.json defines variable json_locale_data
  32  var params = {  "domain" : "myDomain",
  33                  "locale_data" : json_locale_data
  34               };
  35  var gt = new Gettext(params);
  36  // create a shortcut if you'd like
  37  function _ (msgid) { return gt.gettext(msgid); }
  38  alert(_("some string"));
  39  // or use fully named method
  40  alert(gt.gettext("some string"));
  41  // change to use a different "domain"
  42  gt.textdomain("anotherDomain");
  43  alert(gt.gettext("some string"));
  44
  45
  46  // //////////////////////////////////////////////////////////
  47  // The other way to load the language lookup is a "link" tag
  48  // Downside is that not all browsers cache XMLHttpRequests the
  49  // same way, so caching of the language data isn't guarenteed
  50  // across page loads.
  51  // Upside is that it's easy to specify multiple files
  52  <link rel="gettext" href="/path/LC_MESSAGES/myDomain.json" />
  53  <script language="javascript" src="/path/Gettext.js'></script>
  54
  55  var gt = new Gettext({ "domain" : "myDomain" });
  56  // rest is the same
  57
  58
  59  // //////////////////////////////////////////////////////////
  60  // The reson the shortcuts aren't exported by default is because they'd be
  61  // glued to the single domain you created. So, if you're adding i18n support
  62  // to some js library, you should use it as so:
  63
  64  if (typeof(MyNamespace) == 'undefined') MyNamespace = {};
  65  MyNamespace.MyClass = function () {
  66      var gtParms = { "domain" : 'MyNamespace_MyClass' };
  67      this.gt = new Gettext(gtParams);
  68      return this;
  69  };
  70  MyNamespace.MyClass.prototype._ = function (msgid) {
  71      return this.gt.gettext(msgid);
  72  };
  73  MyNamespace.MyClass.prototype.something = function () {
  74      var myString = this._("this will get translated");
  75  };
  76
  77  // //////////////////////////////////////////////////////////
  78  // Adding the shortcuts to a global scope is easier. If that's
  79  // ok in your app, this is certainly easier.
  80  var myGettext = new Gettext({ 'domain' : 'myDomain' });
  81  function _ (msgid) {
  82      return myGettext.gettext(msgid);
  83  }
  84  alert( _("text") );
  85
  86  // //////////////////////////////////////////////////////////
  87  // Data structure of the json data
  88  // NOTE: if you're loading via the <script> tag, you can only
  89  // load one file, but it can contain multiple domains.
  90  var json_locale_data = {
  91      "MyDomain" : {
  92          "" : {
  93              "header_key" : "header value",
  94              "header_key" : "header value",
  95          "msgid" : [ "msgid_plural", "msgstr", "msgstr_plural", "msgstr_pluralN" ],
  96          "msgctxt\004msgid" : [ null, "msgstr" ],
  97          },
  98      "AnotherDomain" : {
  99          },
 100      }
 101
 102 =head1 DESCRIPTION
 103
 104 This is a javascript implementation of GNU Gettext, providing internationalization support for javascript. It differs from existing javascript implementations in that it will support all current Gettext features (ex. plural and context support), and will also support loading language catalogs from .mo, .po, or preprocessed json files (converter included).
 105
 106 The locale initialization differs from that of GNU Gettext / POSIX. Rather than setting the category, domain, and paths, and letting the libs find the right file, you must explicitly load the file at some point. The "domain" will still be honored. Future versions may be expanded to include support for set_locale like features.
 107
 108
 109 =head1 INSTALL
 110
 111 To install this module, simply copy the file lib/Gettext.js to a web accessable location, and reference it from your application.
 112
 113
 114 =head1 CONFIGURATION
 115
 116 Configure in one of two ways:
 117
 118 =over
 119
 120 =item 1. Optimal. Load language definition from statically defined json data.
 121
 122     <script language="javascript" src="/path/locale/domain.json"></script>
 123
 124     // in domain.json
 125     json_locale_data = {
 126         "mydomain" : {
 127             // po header fields
 128             "" : {
 129                 "plural-forms" : "...",
 130                 "lang" : "en",
 131                 },
 132             // all the msgid strings and translations
 133             "msgid" : [ "msgid_plural", "translation", "plural_translation" ],
 134         },
 135     };
 136     // please see the included bin/po2json script for the details on this format
 137
 138 This method also allows you to use unsupported file formats, so long as you can parse them into the above format.
 139
 140 =item 2. Use AJAX to load language file.
 141
 142 Use XMLHttpRequest (actually, SJAX - syncronous) to load an external resource.
 143
 144 Supported external formats are:
 145
 146 =over
 147
 148 =item * Javascript Object Notation (.json)
 149
 150 (see bin/po2json)
 151
 152     type=application/json
 153
 154 =item * Uniforum Portable Object (.po)
 155
 156 (see GNU Gettext's xgettext)
 157
 158     type=application/x-po
 159
 160 =item * Machine Object (compiled .po) (.mo)
 161
 162 NOTE: .mo format isn't actually supported just yet, but support is planned.
 163
 164 (see GNU Gettext's msgfmt)
 165
 166     type=application/x-mo
 167
 168 =back
 169
 170 =back
 171
 172 =head1 METHODS
 173
 174 The following methods are implemented:
 175
 176   new Gettext(args)
 177   textdomain  (domain)
 178   gettext     (msgid)
 179   dgettext    (domainname, msgid)
 180   dcgettext   (domainname, msgid, LC_MESSAGES)
 181   ngettext    (msgid, msgid_plural, count)
 182   dngettext   (domainname, msgid, msgid_plural, count)
 183   dcngettext  (domainname, msgid, msgid_plural, count, LC_MESSAGES)
 184   pgettext    (msgctxt, msgid)
 185   dpgettext   (domainname, msgctxt, msgid)
 186   dcpgettext  (domainname, msgctxt, msgid, LC_MESSAGES)
 187   npgettext   (msgctxt, msgid, msgid_plural, count)
 188   dnpgettext  (domainname, msgctxt, msgid, msgid_plural, count)
 189   dcnpgettext (domainname, msgctxt, msgid, msgid_plural, count, LC_MESSAGES)
 190   strargs     (string, args_array)
 191
 192
 193 =head2 new Gettext (args)
 194
 195 Several methods of loading locale data are included. You may specify a plugin or alternative method of loading data by passing the data in as the "locale_data" option. For example:
 196
 197     var get_locale_data = function () {
 198         // plugin does whatever to populate locale_data
 199         return locale_data;
 200     };
 201     var gt = new Gettext( 'domain' : 'messages',
 202                           'locale_data' : get_locale_data() );
 203
 204 The above can also be used if locale data is specified in a statically included <SCRIPT> tag. Just specify the variable name in the call to new. Ex:
 205
 206     var gt = new Gettext( 'domain' : 'messages',
 207                           'locale_data' : json_locale_data_variable );
 208
 209 Finally, you may load the locale data by referencing it in a <LINK> tag. Simply exclude the 'locale_data' option, and all <LINK rel="gettext" ...> items will be tried. The <LINK> should be specified as:
 210
 211     <link rel="gettext" type="application/json" href="/path/to/file.json">
 212     <link rel="gettext" type="text/javascript"  href="/path/to/file.json">
 213     <link rel="gettext" type="application/x-po" href="/path/to/file.po">
 214     <link rel="gettext" type="application/x-mo" href="/path/to/file.mo">
 215
 216 args:
 217
 218 =over
 219
 220 =item domain
 221
 222 The Gettext domain, not www.whatev.com. It's usually your applications basename. If the .po file was "myapp.po", this would be "myapp".
 223
 224 =item locale_data
 225
 226 Raw locale data (in json structure). If specified, from_link data will be ignored.
 227
 228 =back
 229
 230 =cut
 231
 232 */
 233
 234 Gettext = function (args) {
 235     this.domain         = 'messages';
 236     // locale_data will be populated from <link...> if not specified in args
 237     this.locale_data    = undefined;
 238
 239     // set options
 240     var options = [ "domain", "locale_data" ];
 241     if (this.isValidObject(args)) {
 242         for (var i in args) {
 243             for (var j=0; j<options.length; j++) {
 244                 if (i == options[j]) {
 245                     // don't set it if it's null or undefined
 246                     if (this.isValidObject(args[i]))
 247                         this[i] = args[i];
 248                 }
 249             }
 250         }
 251     }
 252
 253
 254     // try to load the lang file from somewhere
 255     this.try_load_lang();
 256
 257     return this;
 258 }
 259
 260 Gettext.context_glue = "\004";
 261 Gettext._locale_data = {};
 262
 263 Gettext.prototype.try_load_lang = function() {
 264     // check to see if language is statically included
 265     if (typeof(this.locale_data) != 'undefined') {
 266         // we're going to reformat it, and overwrite the variable
 267         var locale_copy = this.locale_data;
 268         this.locale_data = undefined;
 269         this.parse_locale_data(locale_copy);
 270
 271         if (typeof(Gettext._locale_data[this.domain]) == 'undefined') {
 272             throw new Error("Error: Gettext 'locale_data' does not contain the domain '"+this.domain+"'");
 273         }
 274     }
 275
 276
 277     // try loading from JSON
 278     // get lang links
 279     var lang_link = this.get_lang_refs();
 280
 281     if (typeof(lang_link) == 'object' && lang_link.length > 0) {
 282         // NOTE: there will be a delay here, as this is async.
 283         // So, any i18n calls made right after page load may not
 284         // get translated.
 285         // XXX: we may want to see if we can "fix" this behavior
 286         for (var i=0; i<lang_link.length; i++) {
 287             var link = lang_link[i];
 288             if (link.type == 'application/json') {
 289                 if (! this.try_load_lang_json(link.href) ) {
 290                     throw new Error("Error: Gettext 'try_load_lang_json' failed. Unable to exec xmlhttprequest for link ["+link.href+"]");
 291                 }
 292             } else if (link.type == 'application/x-po') {
 293                 if (! this.try_load_lang_po(link.href) ) {
 294                     throw new Error("Error: Gettext 'try_load_lang_po' failed. Unable to exec xmlhttprequest for link ["+link.href+"]");
 295                 }
 296             } else {
 297                 // TODO: implement the other types (.mo)
 298                 throw new Error("TODO: link type ["+link.type+"] found, and support is planned, but not implemented at this time.");
 299             }
 300         }
 301     }
 302 };
 303
 304 // This takes the bin/po2json'd data, and moves it into an internal form
 305 // for use in our lib, and puts it in our object as:
 306 //  Gettext._locale_data = {
 307 //      domain : {
 308 //          head : { headfield : headvalue },
 309 //          msgs : {
 310 //              msgid : [ msgid_plural, msgstr, msgstr_plural ],
 311 //          },
 312 Gettext.prototype.parse_locale_data = function(locale_data) {
 313     if (typeof(Gettext._locale_data) == 'undefined') {
 314         Gettext._locale_data = { };
 315     }
 316
 317     // suck in every domain defined in the supplied data
 318     for (var domain in locale_data) {
 319         // skip empty specs (flexibly)
 320         if ((! locale_data.hasOwnProperty(domain)) || (! this.isValidObject(locale_data[domain])))
 321             continue;
 322         // skip if it has no msgid's
 323         var has_msgids = false;
 324         for (var msgid in locale_data[domain]) {
 325             has_msgids = true;
 326             break;
 327         }
 328         if (! has_msgids) continue;
 329
 330         // grab shortcut to data
 331         var data = locale_data[domain];
 332
 333         // if they specifcy a blank domain, default to "messages"
 334         if (domain == "") domain = "messages";
 335         // init the data structure
 336         if (! this.isValidObject(Gettext._locale_data[domain]) )
 337             Gettext._locale_data[domain] = { };
 338         if (! this.isValidObject(Gettext._locale_data[domain].head) )
 339             Gettext._locale_data[domain].head = { };
 340         if (! this.isValidObject(Gettext._locale_data[domain].msgs) )
 341             Gettext._locale_data[domain].msgs = { };
 342
 343         for (var key in data) {
 344             if (key == "") {
 345                 var header = data[key];
 346                 for (var head in header) {
 347                     var h = head.toLowerCase();
 348                     Gettext._locale_data[domain].head[h] = header[head];
 349                 }
 350             } else {
 351                 Gettext._locale_data[domain].msgs[key] = data[key];
 352             }
 353         }
 354     }
 355
 356     // build the plural forms function
 357     for (var domain in Gettext._locale_data) {
 358         if (this.isValidObject(Gettext._locale_data[domain].head['plural-forms']) &&
 359             typeof(Gettext._locale_data[domain].head.plural_func) == 'undefined') {
 360             // untaint data
 361             var plural_forms = Gettext._locale_data[domain].head['plural-forms'];
 362             var pf_re = new RegExp('^(\\s*nplurals\\s*=\\s*[0-9]+\\s*;\\s*plural\\s*=\\s*(?:\\s|[-\\?\\|&=!<>+*/%:;a-zA-Z0-9_\(\)])+)', 'm');
 363             if (pf_re.test(plural_forms)) {
 364                 //ex english: "Plural-Forms: nplurals=2; plural=(n != 1);\n"
 365                 //pf = "nplurals=2; plural=(n != 1);";
 366                 //ex russian: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10< =4 && (n%100<10 or n%100>=20) ? 1 : 2)
 367                 //pf = "nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)";
 368
 369                 var pf = Gettext._locale_data[domain].head['plural-forms'];
 370                 if (! /;\s*$/.test(pf)) pf = pf.concat(';');
 371                 /* We used to use eval, but it seems IE has issues with it.
 372                  * We now use "new Function", though it carries a slightly
 373                  * bigger performance hit.
 374                 var code = 'function (n) { var plural; var nplurals; '+pf+' return { "nplural" : nplurals, "plural" : (plural === true ? 1 : plural ? plural : 0) }; };';
 375                 Gettext._locale_data[domain].head.plural_func = eval("("+code+")");
 376                 */
 377                 var code = 'var plural; var nplurals; '+pf+' return { "nplural" : nplurals, "plural" : (plural === true ? 1 : plural ? plural : 0) };';
 378                 Gettext._locale_data[domain].head.plural_func = new Function("n", code);
 379             } else {
 380                 throw new Error("Syntax error in language file. Plural-Forms header is invalid ["+plural_forms+"]");
 381             }
 382
 383         // default to english plural form
 384         } else if (typeof(Gettext._locale_data[domain].head.plural_func) == 'undefined') {
 385             Gettext._locale_data[domain].head.plural_func = function (n) {
 386                 var p = (n != 1) ? 1 : 0;
 387                 return { 'nplural' : 2, 'plural' : p };
 388                 };
 389         } // else, plural_func already created
 390     }
 391
 392     return;
 393 };
 394
 395
 396 // try_load_lang_po : do an ajaxy call to load in the .po lang defs
 397 Gettext.prototype.try_load_lang_po = function(uri) {
 398     var data = this.sjax(uri);
 399     if (! data) return;
 400
 401     var domain = this.uri_basename(uri);
 402     var parsed = this.parse_po(data);
 403
 404     var rv = {};
 405     // munge domain into/outof header
 406     if (parsed) {
 407         if (! parsed[""]) parsed[""] = {};
 408         if (! parsed[""]["domain"]) parsed[""]["domain"] = domain;
 409         domain = parsed[""]["domain"];
 410         rv[domain] = parsed;
 411
 412         this.parse_locale_data(rv);
 413     }
 414
 415     return 1;
 416 };
 417
 418 Gettext.prototype.uri_basename = function(uri) {
 419     var rv;
 420     if (rv = uri.match(/^(.*\/)?(.*)/)) {
 421         var ext_strip;
 422         if (ext_strip = rv[2].match(/^(.*)\..+$/))
 423             return ext_strip[1];
 424         else
 425             return rv[2];
 426     } else {
 427         return "";
 428     }
 429 };
 430
 431 Gettext.prototype.parse_po = function(data) {
 432     var rv = {};
 433     var buffer = {};
 434     var lastbuffer = "";
 435     var errors = [];
 436     var lines = data.split("\n");
 437     for (var i=0; i<lines.length; i++) {
 438         // chomp
 439         lines[i] = lines[i].replace(/(\n|\r)+$/, '');
 440
 441         var match;
 442
 443         // Empty line / End of an entry.
 444         if (/^$/.test(lines[i])) {
 445             if (typeof(buffer['msgid']) != 'undefined') {
 446                 var msg_ctxt_id = (typeof(buffer['msgctxt']) != 'undefined' &&
 447                                    buffer['msgctxt'].length) ?
 448                                   buffer['msgctxt']+Gettext.context_glue+buffer['msgid'] :
 449                                   buffer['msgid'];
 450                 var msgid_plural = (typeof(buffer['msgid_plural']) != 'undefined' &&
 451                                     buffer['msgid_plural'].length) ?
 452                                    buffer['msgid_plural'] :
 453                                    null;
 454
 455                 // find msgstr_* translations and push them on
 456                 var trans = [];
 457                 for (var str in buffer) {
 458                     var match;
 459                     if (match = str.match(/^msgstr_(\d+)/))
 460                         trans[parseInt(match[1])] = buffer[str];
 461                 }
 462                 trans.unshift(msgid_plural);
 463
 464                 // only add it if we've got a translation
 465                 // NOTE: this doesn't conform to msgfmt specs
 466                 if (trans.length > 1) rv[msg_ctxt_id] = trans;
 467
 468                 buffer = {};
 469                 lastbuffer = "";
 470             }
 471
 472         // comments
 473         } else if (/^#/.test(lines[i])) {
 474             continue;
 475
 476         // msgctxt
 477         } else if (match = lines[i].match(/^msgctxt\s+(.*)/)) {
 478             lastbuffer = 'msgctxt';
 479             buffer[lastbuffer] = this.parse_po_dequote(match[1]);
 480
 481         // msgid
 482         } else if (match = lines[i].match(/^msgid\s+(.*)/)) {
 483             lastbuffer = 'msgid';
 484             buffer[lastbuffer] = this.parse_po_dequote(match[1]);
 485
 486         // msgid_plural
 487         } else if (match = lines[i].match(/^msgid_plural\s+(.*)/)) {
 488             lastbuffer = 'msgid_plural';
 489             buffer[lastbuffer] = this.parse_po_dequote(match[1]);
 490
 491         // msgstr
 492         } else if (match = lines[i].match(/^msgstr\s+(.*)/)) {
 493             lastbuffer = 'msgstr_0';
 494             buffer[lastbuffer] = this.parse_po_dequote(match[1]);
 495
 496         // msgstr[0] (treak like msgstr)
 497         } else if (match = lines[i].match(/^msgstr\[0\]\s+(.*)/)) {
 498             lastbuffer = 'msgstr_0';
 499             buffer[lastbuffer] = this.parse_po_dequote(match[1]);
 500
 501         // msgstr[n]
 502         } else if (match = lines[i].match(/^msgstr\[(\d+)\]\s+(.*)/)) {
 503             lastbuffer = 'msgstr_'+match[1];
 504             buffer[lastbuffer] = this.parse_po_dequote(match[2]);
 505
 506         // continued string
 507         } else if (/^"/.test(lines[i])) {
 508             buffer[lastbuffer] += this.parse_po_dequote(lines[i]);
 509
 510         // something strange
 511         } else {
 512             errors.push("Strange line ["+i+"] : "+lines[i]);
 513         }
 514     }
 515
 516
 517     // handle the final entry
 518     if (typeof(buffer['msgid']) != 'undefined') {
 519         var msg_ctxt_id = (typeof(buffer['msgctxt']) != 'undefined' &&
 520                            buffer['msgctxt'].length) ?
 521                           buffer['msgctxt']+Gettext.context_glue+buffer['msgid'] :
 522                           buffer['msgid'];
 523         var msgid_plural = (typeof(buffer['msgid_plural']) != 'undefined' &&
 524                             buffer['msgid_plural'].length) ?
 525                            buffer['msgid_plural'] :
 526                            null;
 527
 528         // find msgstr_* translations and push them on
 529         var trans = [];
 530         for (var str in buffer) {
 531             var match;
 532             if (match = str.match(/^msgstr_(\d+)/))
 533                 trans[parseInt(match[1])] = buffer[str];
 534         }
 535         trans.unshift(msgid_plural);
 536
 537         // only add it if we've got a translation
 538         // NOTE: this doesn't conform to msgfmt specs
 539         if (trans.length > 1) rv[msg_ctxt_id] = trans;
 540
 541         buffer = {};
 542         lastbuffer = "";
 543     }
 544
 545
 546     // parse out the header
 547     if (rv[""] && rv[""][1]) {
 548         var cur = {};
 549         var hlines = rv[""][1].split(/\\n/);
 550         for (var i=0; i<hlines.length; i++) {
 551             if (! hlines.length) continue;
 552
 553             var pos = hlines[i].indexOf(':', 0);
 554             if (pos != -1) {
 555                 var key = hlines[i].substring(0, pos);
 556                 var val = hlines[i].substring(pos +1);
 557                 var keylow = key.toLowerCase();
 558
 559                 if (cur[keylow] && cur[keylow].length) {
 560                     errors.push("SKIPPING DUPLICATE HEADER LINE: "+hlines[i]);
 561                 } else if (/#-#-#-#-#/.test(keylow)) {
 562                     errors.push("SKIPPING ERROR MARKER IN HEADER: "+hlines[i]);
 563                 } else {
 564                     // remove begining spaces if any
 565                     val = val.replace(/^\s+/, '');
 566                     cur[keylow] = val;
 567                 }
 568
 569             } else {
 570                 errors.push("PROBLEM LINE IN HEADER: "+hlines[i]);
 571                 cur[hlines[i]] = '';
 572             }
 573         }
 574
 575         // replace header string with assoc array
 576         rv[""] = cur;
 577     } else {
 578         rv[""] = {};
 579     }
 580
 581     // TODO: XXX: if there are errors parsing, what do we want to do?
 582     // GNU Gettext silently ignores errors. So will we.
 583     // alert( "Errors parsing po file:\n" + errors.join("\n") );
 584
 585     return rv;
 586 };
 587
 588
 589 Gettext.prototype.parse_po_dequote = function(str) {
 590     var match;
 591     if (match = str.match(/^"(.*)"/)) {
 592         str = match[1];
 593     }
 594     // unescale all embedded quotes (fixes bug #17504)
 595     str = str.replace(/\\"/g, "\"");
 596     return str;
 597 };
 598
 599
 600 // try_load_lang_json : do an ajaxy call to load in the lang defs
 601 Gettext.prototype.try_load_lang_json = function(uri) {
 602     var data = this.sjax(uri);
 603     if (! data) return;
 604
 605     var rv = this.JSON(data);
 606     this.parse_locale_data(rv);
 607
 608     return 1;
 609 };
 610
 611 // this finds all <link> tags, filters out ones that match our
 612 // specs, and returns a list of hashes of those
 613 Gettext.prototype.get_lang_refs = function() {
 614     var langs = new Array();
 615     var links = document.getElementsByTagName("link");
 616     // find all <link> tags in dom; filter ours
 617     for (var i=0; i<links.length; i++) {
 618         if (links[i].rel == 'gettext' && links[i].href) {
 619             if (typeof(links[i].type) == 'undefined' ||
 620                 links[i].type == '') {
 621                 if (/\.json$/i.test(links[i].href)) {
 622                     links[i].type = 'application/json';
 623                 } else if (/\.js$/i.test(links[i].href)) {
 624                     links[i].type = 'application/json';
 625                 } else if (/\.po$/i.test(links[i].href)) {
 626                     links[i].type = 'application/x-po';
 627                 } else if (/\.mo$/i.test(links[i].href)) {
 628                     links[i].type = 'application/x-mo';
 629                 } else {
 630                     throw new Error("LINK tag with rel=gettext found, but the type and extension are unrecognized.");
 631                 }
 632             }
 633
 634             links[i].type = links[i].type.toLowerCase();
 635             if (links[i].type == 'application/json') {
 636                 links[i].type = 'application/json';
 637             } else if (links[i].type == 'text/javascript') {
 638                 links[i].type = 'application/json';
 639             } else if (links[i].type == 'application/x-po') {
 640                 links[i].type = 'application/x-po';
 641             } else if (links[i].type == 'application/x-mo') {
 642                 links[i].type = 'application/x-mo';
 643             } else {
 644                 throw new Error("LINK tag with rel=gettext found, but the type attribute ["+links[i].type+"] is unrecognized.");
 645             }
 646
 647             langs.push(links[i]);
 648         }
 649     }
 650     return langs;
 651 };
 652
 653
 654 /*
 655
 656 =head2 textdomain( domain )
 657
 658 Set domain for future gettext() calls
 659
 660 A  message  domain  is  a  set of translatable msgid messages. Usually,
 661 every software package has its own message domain. The domain  name  is
 662 used to determine the message catalog where a translation is looked up;
 663 it must be a non-empty string.
 664
 665 The current message domain is used by the gettext, ngettext, pgettext,
 666 npgettext functions, and by the dgettext, dcgettext, dngettext, dcngettext,
 667 dpgettext, dcpgettext, dnpgettext and dcnpgettext functions when called
 668 with a NULL domainname argument.
 669
 670 If domainname is not NULL, the current message domain is set to
 671 domainname.
 672
 673 If domainname is undefined, null, or empty string, the function returns
 674 the current message domain.
 675
 676 If  successful,  the  textdomain  function  returns the current message
 677 domain, after possibly changing it. (ie. if you set a new domain, the
 678 value returned will NOT be the previous domain).
 679
 680 =cut
 681
 682 */
 683 Gettext.prototype.textdomain = function (domain) {
 684     if (domain && domain.length) this.domain = domain;
 685     return this.domain;
 686 }
 687
 688 /*
 689
 690 =head2 gettext( MSGID )
 691
 692 Returns the translation for B<MSGID>.  Example:
 693
 694     alert( gt.gettext("Hello World!\n") );
 695
 696 If no translation can be found, the unmodified B<MSGID> is returned,
 697 i. e. the function can I<never> fail, and will I<never> mess up your
 698 original message.
 699
 700 One common mistake is to interpolate a variable into the string like this:
 701
 702   var translated = gt.gettext("Hello " + full_name);
 703
 704 The interpolation will happen before it's passed to gettext, and it's
 705 unlikely you'll have a translation for every "Hello Tom" and "Hello Dick"
 706 and "Hellow Harry" that may arise.
 707
 708 Use C<strargs()> (see below) to solve this problem:
 709
 710   var translated = Gettext.strargs( gt.gettext("Hello %1"), [full_name] );
 711
 712 This is espeically useful when multiple replacements are needed, as they
 713 may not appear in the same order within the translation. As an English to
 714 French example:
 715
 716   Expected result: "This is the red ball"
 717   English: "This is the %1 %2"
 718   French:  "C'est le %2 %1"
 719   Code: Gettext.strargs( gt.gettext("This is the %1 %2"), ["red", "ball"] );
 720
 721 (The example is stupid because neither color nor thing will get
 722 translated here ...).
 723
 724 =head2 dgettext( TEXTDOMAIN, MSGID )
 725
 726 Like gettext(), but retrieves the message for the specified
 727 B<TEXTDOMAIN> instead of the default domain.  In case you wonder what
 728 a textdomain is, see above section on the textdomain() call.
 729
 730 =head2 dcgettext( TEXTDOMAIN, MSGID, CATEGORY )
 731
 732 Like dgettext() but retrieves the message from the specified B<CATEGORY>
 733 instead of the default category C<LC_MESSAGES>.
 734
 735 NOTE: the categories are really useless in javascript context. This is
 736 here for GNU Gettext API compatability. In practice, you'll never need
 737 to use this. This applies to all the calls including the B<CATEGORY>.
 738
 739
 740 =head2 ngettext( MSGID, MSGID_PLURAL, COUNT )
 741
 742 Retrieves the correct translation for B<COUNT> items.  In legacy software
 743 you will often find something like:
 744
 745     alert( count + " file(s) deleted.\n" );
 746
 747 or
 748
 749     printf(count + " file%s deleted.\n", $count == 1 ? '' : 's');
 750
 751 I<NOTE: javascript lacks a builtin printf, so the above isn't a working example>
 752
 753 The first example looks awkward, the second will only work in English
 754 and languages with similar plural rules.  Before ngettext() was introduced,
 755 the best practice for internationalized programs was:
 756
 757     if (count == 1) {
 758         alert( gettext("One file deleted.\n") );
 759     } else {
 760         printf( gettext("%d files deleted.\n"), count );
 761     }
 762
 763 This is a nuisance for the programmer and often still not sufficient
 764 for an adequate translation.  Many languages have completely different
 765 ideas on numerals.  Some (French, Italian, ...) treat 0 and 1 alike,
 766 others make no distinction at all (Japanese, Korean, Chinese, ...),
 767 others have two or more plural forms (Russian, Latvian, Czech,
 768 Polish, ...).  The solution is:
 769
 770     printf( ngettext("One file deleted.\n",
 771                      "%d files deleted.\n",
 772                      count), // argument to ngettext!
 773             count);          // argument to printf!
 774
 775 In English, or if no translation can be found, the first argument
 776 (B<MSGID>) is picked if C<count> is one, the second one otherwise.
 777 For other languages, the correct plural form (of 1, 2, 3, 4, ...)
 778 is automatically picked, too.  You don't have to know anything about
 779 the plural rules in the target language, ngettext() will take care
 780 of that.
 781
 782 This is most of the time sufficient but you will have to prove your
 783 creativity in cases like
 784
 785     "%d file(s) deleted, and %d file(s) created.\n"
 786
 787 That said, javascript lacks C<printf()> support. Supplied with Gettext.js
 788 is the C<strargs()> method, which can be used for these cases:
 789
 790     Gettext.strargs( gt.ngettext( "One file deleted.\n",
 791                                   "%d files deleted.\n",
 792                                   count), // argument to ngettext!
 793                      count); // argument to strargs!
 794
 795 NOTE: the variable replacement isn't done for you, so you must
 796 do it yourself as in the above.
 797
 798 =head2 dngettext( TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT )
 799
 800 Like ngettext() but retrieves the translation from the specified
 801 textdomain instead of the default domain.
 802
 803 =head2 dcngettext( TEXTDOMAIN, MSGID, MSGID_PLURAL, COUNT, CATEGORY )
 804
 805 Like dngettext() but retrieves the translation from the specified
 806 category, instead of the default category C<LC_MESSAGES>.
 807
 808
 809 =head2 pgettext( MSGCTXT, MSGID )
 810
 811 Returns the translation of MSGID, given the context of MSGCTXT.
 812
 813 Both items are used as a unique key into the message catalog.
 814
 815 This allows the translator to have two entries for words that may
 816 translate to different foreign words based on their context. For
 817 example, the word "View" may be a noun or a verb, which may be
 818 used in a menu as File->View or View->Source.
 819
 820     alert( pgettext( "Verb: To View", "View" ) );
 821     alert( pgettext( "Noun: A View", "View"  ) );
 822
 823 The above will both lookup different entries in the message catalog.
 824
 825 In English, or if no translation can be found, the second argument
 826 (B<MSGID>) is returned.
 827
 828 =head2 dpgettext( TEXTDOMAIN, MSGCTXT, MSGID )
 829
 830 Like pgettext(), but retrieves the message for the specified
 831 B<TEXTDOMAIN> instead of the default domain.
 832
 833 =head2 dcpgettext( TEXTDOMAIN, MSGCTXT, MSGID, CATEGORY )
 834
 835 Like dpgettext() but retrieves the message from the specified B<CATEGORY>
 836 instead of the default category C<LC_MESSAGES>.
 837
 838
 839 =head2 npgettext( MSGCTXT, MSGID, MSGID_PLURAL, COUNT )
 840
 841 Like ngettext() with the addition of context as in pgettext().
 842
 843 In English, or if no translation can be found, the second argument
 844 (MSGID) is picked if B<COUNT> is one, the third one otherwise.
 845
 846 =head2 dnpgettext( TEXTDOMAIN, MSGCTXT, MSGID, MSGID_PLURAL, COUNT )
 847
 848 Like npgettext() but retrieves the translation from the specified
 849 textdomain instead of the default domain.
 850
 851 =head2 dcnpgettext( TEXTDOMAIN, MSGCTXT, MSGID, MSGID_PLURAL, COUNT, CATEGORY )
 852
 853 Like dnpgettext() but retrieves the translation from the specified
 854 category, instead of the default category C<LC_MESSAGES>.
 855
 856 =cut
 857
 858 */
 859
 860 // gettext
 861 Gettext.prototype.gettext = function (msgid) {
 862     var msgctxt;
 863     var msgid_plural;
 864     var n;
 865     var category;
 866     return this.dcnpgettext(null, msgctxt, msgid, msgid_plural, n, category);
 867 };
 868
 869 Gettext.prototype.dgettext = function (domain, msgid) {
 870     var msgctxt;
 871     var msgid_plural;
 872     var n;
 873     var category;
 874     return this.dcnpgettext(domain, msgctxt, msgid, msgid_plural, n, category);
 875 };
 876
 877 Gettext.prototype.dcgettext = function (domain, msgid, category) {
 878     var msgctxt;
 879     var msgid_plural;
 880     var n;
 881     return this.dcnpgettext(domain, msgctxt, msgid, msgid_plural, n, category);
 882 };
 883
 884 // ngettext
 885 Gettext.prototype.ngettext = function (msgid, msgid_plural, n) {
 886     var msgctxt;
 887     var category;
 888     return this.dcnpgettext(null, msgctxt, msgid, msgid_plural, n, category);
 889 };
 890
 891 Gettext.prototype.dngettext = function (domain, msgid, msgid_plural, n) {
 892     var msgctxt;
 893     var category;
 894     return this.dcnpgettext(domain, msgctxt, msgid, msgid_plural, n, category);
 895 };
 896
 897 Gettext.prototype.dcngettext = function (domain, msgid, msgid_plural, n, category) {
 898     var msgctxt;
 899     return this.dcnpgettext(domain, msgctxt, msgid, msgid_plural, n, category, category);
 900 };
 901
 902 // pgettext
 903 Gettext.prototype.pgettext = function (msgctxt, msgid) {
 904     var msgid_plural;
 905     var n;
 906     var category;
 907     return this.dcnpgettext(null, msgctxt, msgid, msgid_plural, n, category);
 908 };
 909
 910 Gettext.prototype.dpgettext = function (domain, msgctxt, msgid) {
 911     var msgid_plural;
 912     var n;
 913     var category;
 914     return this.dcnpgettext(domain, msgctxt, msgid, msgid_plural, n, category);
 915 };
 916
 917 Gettext.prototype.dcpgettext = function (domain, msgctxt, msgid, category) {
 918     var msgid_plural;
 919     var n;
 920     return this.dcnpgettext(domain, msgctxt, msgid, msgid_plural, n, category);
 921 };
 922
 923 // npgettext
 924 Gettext.prototype.npgettext = function (msgctxt, msgid, msgid_plural, n) {
 925     var category;
 926     return this.dcnpgettext(null, msgctxt, msgid, msgid_plural, n, category);
 927 };
 928
 929 Gettext.prototype.dnpgettext = function (domain, msgctxt, msgid, msgid_plural, n) {
 930     var category;
 931     return this.dcnpgettext(domain, msgctxt, msgid, msgid_plural, n, category);
 932 };
 933
 934 // this has all the options, so we use it for all of them.
 935 Gettext.prototype.dcnpgettext = function (domain, msgctxt, msgid, msgid_plural, n, category) {
 936     if (! this.isValidObject(msgid)) return '';
 937
 938     var plural = this.isValidObject(msgid_plural);
 939     var msg_ctxt_id = this.isValidObject(msgctxt) ? msgctxt+Gettext.context_glue+msgid : msgid;
 940
 941     var domainname = this.isValidObject(domain)      ? domain :
 942                      this.isValidObject(this.domain) ? this.domain :
 943                                                        'messages';
 944
 945     // category is always LC_MESSAGES. We ignore all else
 946     var category_name = 'LC_MESSAGES';
 947     var category = 5;
 948
 949     var locale_data = new Array();
 950     if (typeof(Gettext._locale_data) != 'undefined' &&
 951         this.isValidObject(Gettext._locale_data[domainname])) {
 952         locale_data.push( Gettext._locale_data[domainname] );
 953
 954     } else if (typeof(Gettext._locale_data) != 'undefined') {
 955         // didn't find domain we're looking for. Search all of them.
 956         for (var dom in Gettext._locale_data) {
 957             locale_data.push( Gettext._locale_data[dom] );
 958         }
 959     }
 960
 961     var trans = [];
 962     var found = false;
 963     var domain_used; // so we can find plural-forms if needed
 964     if (locale_data.length) {
 965         for (var i=0; i<locale_data.length; i++) {
 966             var locale = locale_data[i];
 967             if (this.isValidObject(locale.msgs[msg_ctxt_id])) {
 968                 // make copy of that array (cause we'll be destructive)
 969                 for (var j=0; j<locale.msgs[msg_ctxt_id].length; j++) {
 970                     trans[j] = locale.msgs[msg_ctxt_id][j];
 971                 }
 972                 trans.shift(); // throw away the msgid_plural
 973                 domain_used = locale;
 974                 found = true;
 975                 // only break if found translation actually has a translation.
 976                 if ( trans.length > 0 && trans[0].length != 0 )
 977                     break;
 978             }
 979         }
 980     }
 981
 982     // default to english if we lack a match, or match has zero length
 983     if ( trans.length == 0 || trans[0].length == 0 ) {
 984         trans = [ msgid, msgid_plural ];
 985     }
 986
 987     var translation = trans[0];
 988     if (plural) {
 989         var p;
 990         if (found && this.isValidObject(domain_used.head.plural_func) ) {
 991             var rv = domain_used.head.plural_func(n);
 992             if (! rv.plural) rv.plural = 0;
 993             if (! rv.nplural) rv.nplural = 0;
 994             // if plurals returned is out of bound for total plural forms
 995             if (rv.nplural <= rv.plural) rv.plural = 0;
 996             p = rv.plural;
 997         } else {
 998             p = (n != 1) ? 1 : 0;
 999         }
1000         if (this.isValidObject(trans[p]))
1001             translation = trans[p];
1002     }
1003
1004     return translation;
1005 };
1006
1007
1008 /*
1009
1010 =head2 strargs (string, argument_array)
1011
1012   string : a string that potentially contains formatting characters.
1013   argument_array : an array of positional replacement values
1014
1015 This is a utility method to provide some way to support positional parameters within a string, as javascript lacks a printf() method.
1016
1017 The format is similar to printf(), but greatly simplified (ie. fewer features).
1018
1019 Any percent signs followed by numbers are replaced with the corrosponding item from the B<argument_array>.
1020
1021 Example:
1022
1023     var string = "%2 roses are red, %1 violets are blue";
1024     var args   = new Array("10", "15");
1025     var result = Gettext.strargs(string, args);
1026     // result is "15 roses are red, 10 violets are blue"
1027
1028 The format numbers are 1 based, so the first itme is %1.
1029
1030 A lone percent sign may be escaped by preceeding it with another percent sign.
1031
1032 A percent sign followed by anything other than a number or another percent sign will be passed through as is.
1033
1034 Some more examples should clear up any abmiguity. The following were called with the orig string, and the array as Array("[one]", "[two]") :
1035
1036   orig string "blah" becomes "blah"
1037   orig string "" becomes ""
1038   orig string "%%" becomes "%"
1039   orig string "%%%" becomes "%%"
1040   orig string "%%%%" becomes "%%"
1041   orig string "%%%%%" becomes "%%%"
1042   orig string "tom%%dick" becomes "tom%dick"
1043   orig string "thing%1bob" becomes "thing[one]bob"
1044   orig string "thing%1%2bob" becomes "thing[one][two]bob"
1045   orig string "thing%1asdf%2asdf" becomes "thing[one]asdf[two]asdf"
1046   orig string "%1%2%3" becomes "[one][two]"
1047   orig string "tom%1%%2%aDick" becomes "tom[one]%2%aDick"
1048
1049 This is especially useful when using plurals, as the string will nearly always contain the number.
1050
1051 It's also useful in translated strings where the translator may have needed to move the position of the parameters.
1052
1053 For example:
1054
1055   var count = 14;
1056   Gettext.strargs( gt.ngettext('one banana', '%1 bananas', count), [count] );
1057
1058 NOTE: this may be called as an instance method, or as a class method.
1059
1060   // instance method:
1061   var gt = new Gettext(params);
1062   gt.strargs(string, args);
1063
1064   // class method:
1065   Gettext.strargs(string, args);
1066
1067 =cut
1068
1069 */
1070 /* utility method, since javascript lacks a printf */
1071 Gettext.strargs = function (str, args) {
1072     // make sure args is an array
1073     if ( null == args ||
1074          'undefined' == typeof(args) ) {
1075         args = [];
1076     } else if (args.constructor != Array) {
1077         args = [args];
1078     }
1079
1080     // NOTE: javascript lacks support for zero length negative look-behind
1081     // in regex, so we must step through w/ index.
1082     // The perl equiv would simply be:
1083     //    $string =~ s/(?<!\%)\%([0-9]+)/$args[$1]/g;
1084     //    $string =~ s/\%\%/\%/g; # restore escaped percent signs
1085
1086     var newstr = "";
1087     while (true) {
1088         var i = str.indexOf('%');
1089         var match_n;
1090
1091         // no more found. Append whatever remains
1092         if (i == -1) {
1093             newstr += str;
1094             break;
1095         }
1096
1097         // we found it, append everything up to that
1098         newstr += str.substr(0, i);
1099
1100         // check for escpaed %%
1101         if (str.substr(i, 2) == '%%') {
1102             newstr += '%';
1103             str = str.substr((i+2));
1104
1105         // % followed by number
1106         } else if ( match_n = str.substr(i).match(/^%(\d+)/) ) {
1107             var arg_n = parseInt(match_n[1]);
1108             var length_n = match_n[1].length;
1109             if ( arg_n > 0 && args[arg_n -1] != null && typeof(args[arg_n -1]) != 'undefined' )
1110                 newstr += args[arg_n -1];
1111             str = str.substr( (i + 1 + length_n) );
1112
1113         // % followed by some other garbage - just remove the %
1114         } else {
1115             newstr += '%';
1116             str = str.substr((i+1));
1117         }
1118     }
1119
1120     return newstr;
1121 }
1122
1123 /* instance method wrapper of strargs */
1124 Gettext.prototype.strargs = function (str, args) {
1125     return Gettext.strargs(str, args);
1126 }
1127
1128 /* verify that something is an array */
1129 Gettext.prototype.isArray = function (thisObject) {
1130     return this.isValidObject(thisObject) && thisObject.constructor == Array;
1131 };
1132
1133 /* verify that an object exists and is valid */
1134 Gettext.prototype.isValidObject = function (thisObject) {
1135     if (null == thisObject) {
1136         return false;
1137     } else if ('undefined' == typeof(thisObject) ) {
1138         return false;
1139     } else {
1140         return true;
1141     }
1142 };
1143
1144 Gettext.prototype.sjax = function (uri) {
1145     var xmlhttp;
1146     if (window.XMLHttpRequest) {
1147         xmlhttp = new XMLHttpRequest();
1148     } else if (navigator.userAgent.toLowerCase().indexOf('msie 5') != -1) {
1149         xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");
1150     } else {
1151         xmlhttp = new ActiveXObject("Msxml2.XMLHTTP");
1152     }
1153
1154     if (! xmlhttp)
1155         throw new Error("Your browser doesn't do Ajax. Unable to support external language files.");
1156
1157     xmlhttp.open('GET', uri, false);
1158     try { xmlhttp.send(null); }
1159     catch (e) { return; }
1160
1161     // we consider status 200 and 0 as ok.
1162     // 0 happens when we request local file, allowing this to run on local files
1163     var sjax_status = xmlhttp.status;
1164     if (sjax_status == 200 || sjax_status == 0) {
1165         return xmlhttp.responseText;
1166     } else {
1167         var error = xmlhttp.statusText + " (Error " + xmlhttp.status + ")";
1168         if (xmlhttp.responseText.length) {
1169             error += "\n" + xmlhttp.responseText;
1170         }
1171         alert(error);
1172         return;
1173     }
1174 }
1175
1176 Gettext.prototype.JSON = function (data) {
1177     return eval('(' + data + ')');
1178 }
1179
1180
1181 /*
1182
1183 =head1 NOTES
1184
1185 These are some notes on the internals
1186
1187 =over
1188
1189 =item LOCALE CACHING
1190
1191 Loaded locale data is currently cached class-wide. This means that if two scripts are both using Gettext.js, and both share the same gettext domain, that domain will only be loaded once. This will allow you to grab a new object many times from different places, utilize the same domain, and share a single translation file. The downside is that a domain won't be RE-loaded if a new object is instantiated on a domain that had already been instantiated.
1192
1193 =back
1194
1195 =head1 BUGS / TODO
1196
1197 =over
1198
1199 =item error handling
1200
1201 Currently, there are several places that throw errors. In GNU Gettext, there are no fatal errors, which allows text to still be displayed regardless of how broken the environment becomes. We should evaluate and determine where we want to stand on that issue.
1202
1203 =item syncronous only support (no ajax support)
1204
1205 Currently, fetching language data is done purely syncronous, which means the page will halt while those files are fetched/loaded.
1206
1207 This is often what you want, as then following translation requests will actually be translated. However, if all your calls are done dynamically (ie. error handling only or something), loading in the background may be more adventagous.
1208
1209 It's still recommended to use the statically defined <script ...> method, which should have the same delay, but it will cache the result.
1210
1211 =item domain support
1212
1213 domain support while using shortcut methods like C<_('string')> or C<i18n('string')>.
1214
1215 Under normal apps, the domain is usually set globally to the app, and a single language file is used. Under javascript, you may have multiple libraries or applications needing translation support, but the namespace is essentially global.
1216
1217 It's recommended that your app initialize it's own shortcut with it's own domain.  (See examples/wrapper/i18n.js for an example.)
1218
1219 Basically, you'll want to accomplish something like this:
1220
1221     // in some other .js file that needs i18n
1222     this.i18nObj = new i18n;
1223     this.i18n = this.i18nObj.init('domain');
1224     // do translation
1225     alert( this.i18n("string") );
1226
1227 If you use this raw Gettext object, then this is all handled for you, as you have your own object then, and will be calling C<myGettextObject.gettext('string')> and such.
1228
1229
1230 =item encoding
1231
1232 May want to add encoding/reencoding stuff. See GNU iconv, or the perl module Locale::Recode from libintl-perl.
1233
1234 =back
1235
1236
1237 =head1 COMPATABILITY
1238
1239 This has been tested on the following browsers. It may work on others, but these are all those to which I have access.
1240
1241     FF1.5, FF2, FF3, IE6, IE7, Opera9, Opera10, Safari3.1, Chrome
1242
1243     *FF = Firefox
1244     *IE = Internet Explorer
1245
1246
1247 =head1 REQUIRES
1248
1249 bin/po2json requires perl, and the perl modules Locale::PO and JSON.
1250
1251 =head1 SEE ALSO
1252
1253 bin/po2json (included),
1254 examples/normal/index.html,
1255 examples/wrapper/i18n.html, examples/wrapper/i18n.js,
1256 Locale::gettext_pp(3pm), POSIX(3pm), gettext(1), gettext(3)
1257
1258 =head1 AUTHOR
1259
1260 Copyright (C) 2008, Joshua I. Miller E<lt>unrtst@cpan.orgE<gt>, all rights reserved. See the source code for details.
1261
1262 =cut
1263
1264 */