/js/jsgettext/resources/Gettext.js

https://bitbucket.org/fanstatic/js.jsgettext · JavaScript · 1265 lines · 507 code · 93 blank · 665 comment · 177 complexity · 946e49b92105ab018e1aefb782122c42 MD5 · raw file

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