gettext.js Documentation Release 1.0 Jonas Obrist Jul 23, 2017
Contents 1 Installation 3 1.1 Dependencies............................................... 3 1.2 Installation................................................ 3 2 Usage 5 2.1 Workflow................................................. 5 2.2 Compiler................................................. 5 2.3 Runtime................................................. 6 3 Reference 9 3.1 CLI.................................................... 9 3.2 Javascript................................................. 9 4 Changelog 11 4.1 1.2.................................................... 11 4.2 1.1.................................................... 11 4.3 1.0.................................................... 11 5 Indices and tables 13 i
ii
gettext.js Documentation, Release 1.0 gettext.js provides a GNU gettext like interface for use in browsers. For better performance and compatibility, mo files are compiled into JSON or JavaScript files using a Python command line tool. These files can then be used in the browser to provide internationalization capabilities. While the tool to compile mo files to JavaScript or JSON is written in Python, the runtime has no Python dependencies. The JavaScript runtime can be used in either the browser or node. Contents 1
gettext.js Documentation, Release 1.0 2 Contents
CHAPTER 1 Installation Dependencies Compiler Python 3.5 or higher Javascript runtime No dependencies Installation Compiler pip3 install gettextjs Javascript runtime You can install gettext.js via npm or download the file from the dist folder in the repository. The npm package includes the jsnext:main key, so the library can be included via rollupjs and the node-resolve plugin if you re building an ES6 project. For node project, there is also a common-js file. If you wish to use gettext.js in the browser, make sure to use the gettext.iife.js file. 3
gettext.js Documentation, Release 1.0 4 Chapter 1. Installation
CHAPTER 2 Usage Workflow 1. Create your po files using your current workflow. 2. Create your mo files using your current workflow. 3. Use gettextjs to compile those mo files to.mo.js or.mo.json files. 4. Serve the output directory of the gettextjs call in your web app. 5. Use the Javascript runtime to translate your web app. The only thing that really changes from your current workflow is that after compiling the mo files, you then compile them into something that can be used in Javascript. Compiler Let s assume you have the following directory tree: /app/ - locale - en - LC_MESSAGES - messages.mo - messages.po The compiler takes a locale directory as created by gettext ( <locale>/lc_messages/<domain>.mo) as input, and writes the result to an output directory (<locale>/lc_messages/<domain>.mo.<json js>). This output directory should be served by your web server if you use json files. If you use js files you can host them anywhere you want, as you ll be responsible for loading them on your page. In it s most basic form, you simply use gettextjs /app/locale/. Your directory tree now looks like this: 5
gettext.js Documentation, Release 1.0 /app/ - locale - en - LC_MESSAGES - messages.mo - messages.mo.json - messages.po To instead generate JS files, use the --js flag. The JS files will have a single variable in them: <locale>_<domain>, with both of those values in upper-case. So the English messages.mo file will become a variable called EN_MESSAGES. For debugging, you can use the -v/--verbose flag for some more feedback on what is going on. --indent flag can be used to indent the JSON/JS file being generated. You may optionally provide a separate directory for the resulting compiled files. The -i/ Runtime This section assumes you have the locale directory containing the files compiled by gettextjs available at https://example.com/locale/. So for example the English messages.mo.json is available via https://example.com/locale/en/lc_messages/messages.mo.json. Loading (JSON) To load a catalog from a JSON file, use Gettext.load(), so for example to load the English messages domain, you would use the following: Gettext.load('https://example.com/locale', 'en', 'messages').then(function(gettext){ // start using gettext }, function(error){ // handle the error }); Loading (JS) Simply load the file via a script tag: <script src="https://example.com/locale/en/lc_messages/messages.mo.js"></script> Using gettextjs exposed two methods on the Gettext() class: gettext() and ngettext(). They re equivalent to gettext(3) and ngettext(3). gettext() takes a single msgid and returns the translation for it, if it finds one, or the msgid. ngettext() is used for translations which may have plurals. Here s an example usage: Gettext.load('https://example.com/locale', 'en', 'messages').then(function(gettext){ gettext.gettext("hello world!"); gettext.gettext("i know %(number)s language", "I know %(number)s languages", 1); 6 Chapter 2. Usage
gettext.js Documentation, Release 1.0 }); gettext.gettext("i know %(number)s language", "I know %(number)s languages", 2); String interpolation gettext.js does not provide string interpolation. Use libraries like sprintf.js to do this. When doing string interpolation, make sure you call the approprate gettext.js function first. You should always use named arguments when internationalizing strings, as different languages may have different word orders. The example above would become: sprintf(gettext.gettext("i know %(number)s language", "I know %(number)s languages", 2), {'number': 2}); 2.3. Runtime 7
gettext.js Documentation, Release 1.0 8 Chapter 2. Usage
CHAPTER 3 Reference CLI locale_dir Location of your locale directory with your.mo files. Must be in the standard <locale>/lc_messages/ <domain>.mo structure. out_dir Output directory. Defaults to the same as locale_dir. -i, --indent Indent the generated JSON/JS. -v, --verbose Print what files have been compiled. --json Generate JSON files instead of JS files. Javascript class Gettext(catalog) gettext(msgid) Arguments msgid (string) Message ID to look up. Returns Translated string (or input string if not found). ngettext(msgid, msgid_plural, count) Arguments 9
gettext.js Documentation, Release 1.0 msgid (string) Message ID for the singular string. msgid_plural (string) Message ID for the plural string. count (number) Used to detect whether plural or singular form should be used. Returns Translated string (or one of the input strings if not found). set_catalog(catalog) Set a catalog as the currently active, global translation catalog. This can be either an instance of Gettext or the JSON object produced by the compiler. gettext(msgid) Arguments msgid (string) Message ID to look up. Returns Translated string (or input string if not found). Uses the catalog set by set_catalog() to translate a message ID. ngettext(msgid, msgid_plural, count) Arguments msgid (string) Message ID for the singular string. msgid_plural (string) Message ID for the plural string. count (number) Used to detect whether plural or singular form should be used. Returns Translated string (or one of the input strings if not found). Uses the catalog set by set_catalog() to translate a message ID. 10 Chapter 3. Reference
CHAPTER 4 Changelog 1.2 Release date: January 20, 2017 Removed eval from Javascript runtime. Use yarn for development Javascript dependencies. 1.1 Release date: September 24, 2016 Made the JavaScript runtime an NPM package. Removed the Gettext.load API. If you want to load catalogs via AJAX, please use the AJAX libary of your choice. Added global APIs set_catalog(), gettext() and ngettext(). Removed docopt as a dependency for the compiler. The compiler now only depends on Python 3.5. 1.0 Release date: Dec 25, 2015 Initial release. 11
gettext.js Documentation, Release 1.0 12 Chapter 4. Changelog
CHAPTER 5 Indices and tables genindex modindex search 13
gettext.js Documentation, Release 1.0 14 Chapter 5. Indices and tables
Index Symbols json gettextjs command line option, 9 -i, indent gettextjs command line option, 9 -v, verbose gettextjs command line option, 9 G gettext() (built-in function), 9, 10 Gettext() (class), 9 gettextjs command line option json, 9 -i, indent, 9 -v, verbose, 9 locale_dir, 9 out_dir, 9 L locale_dir gettextjs command line option, 9 N ngettext() (built-in function), 9, 10 O out_dir gettextjs command line option, 9 S set_catalog() (built-in function), 10 15