What is gettext-parser?
The gettext-parser npm package is a tool for parsing and compiling gettext files, which are commonly used for internationalization and localization of software. It supports both .po (Portable Object) and .mo (Machine Object) file formats.
What are gettext-parser's main functionalities?
Parsing .po files
This feature allows you to parse .po files into a JavaScript object. The code sample reads a .po file from the filesystem and parses it using gettext-parser.
const gettextParser = require('gettext-parser');
const fs = require('fs');
const input = fs.readFileSync('path/to/your/file.po');
const po = gettextParser.po.parse(input);
console.log(po);
Compiling .po files to .mo files
This feature allows you to compile .po files into .mo files. The code sample reads a .po file, parses it, compiles it into a .mo file, and writes the .mo file to the filesystem.
const gettextParser = require('gettext-parser');
const fs = require('fs');
const input = fs.readFileSync('path/to/your/file.po');
const po = gettextParser.po.parse(input);
const mo = gettextParser.mo.compile(po);
fs.writeFileSync('path/to/your/file.mo', mo);
Parsing .mo files
This feature allows you to parse .mo files into a JavaScript object. The code sample reads a .mo file from the filesystem and parses it using gettext-parser.
const gettextParser = require('gettext-parser');
const fs = require('fs');
const input = fs.readFileSync('path/to/your/file.mo');
const mo = gettextParser.mo.parse(input);
console.log(mo);
Compiling .mo files to .po files
This feature allows you to compile .mo files into .po files. The code sample reads a .mo file, parses it, compiles it into a .po file, and writes the .po file to the filesystem.
const gettextParser = require('gettext-parser');
const fs = require('fs');
const input = fs.readFileSync('path/to/your/file.mo');
const mo = gettextParser.mo.parse(input);
const po = gettextParser.po.compile(mo);
fs.writeFileSync('path/to/your/file.po', po);
Other packages similar to gettext-parser
node-gettext
node-gettext is a comprehensive library for handling gettext translations in Node.js. It provides functionalities for loading, parsing, and managing translations, similar to gettext-parser, but also includes additional features like translation context management and plural forms handling.
i18next
i18next is a powerful internationalization framework for JavaScript. While it does not focus solely on gettext files, it supports a wide range of translation formats and provides extensive features for managing translations, including interpolation, nesting, and pluralization. It is more feature-rich compared to gettext-parser but may be overkill if you only need to handle gettext files.
gettext.js
gettext.js is a lightweight library for handling gettext translations in JavaScript. It provides basic functionalities for parsing and compiling .po and .mo files, similar to gettext-parser, but with a simpler API and fewer features.
gettext-parser
Parse and compile gettext po and mo files with node.js, nothing more, nothing less.
This module is slightly based on my other gettext related module node-gettext. The plan is to move all parsing and compiling logic from node-gettext to here and leave only translation related functions (domains, plural handling, lookups etc.).
If you get a bunchload of warnings or (non fatal) errors when installing, it is ok. These are most probably generated by the optional iconv dependency.
Usage
Include the library:
var gettextParser = require("gettext-parser");
Available methods:
gettextParser.po.parse(buf[, defaultCharset])
where buf
is a po file as a Buffer or an unicode string. defaultCharset
is the charset to use if charset is not defined or is the default "CHARSET"
. Returns gettext-parser specific translation object (see below)gettextParser.po.compile(obj)
where obj
is a translation object, returns a po file as a BuffergettextParser.mo.parse(buf[, defaultCharset])
where buf
is a mo file as a Buffer (mo is binary format, so do not use strings). defaultCharset
is the charset to use if charset is not defined or is the default "CHARSET"
. Returns translation objectgettextParser.mo.compile(obj)
where obj
is a translation object, returns a mo file as a Buffer
NB if you are compiling a previously parsed translation object, you can override the output charset with the charset
property (applies both for compiling mo and po files).
var obj = gettextParser.po.parse(inputBuf);
obj.charset = "windows-1257";
outputBuf = gettextParser.po.compile(obj);
Headers for the output are modified to match the updated charset.
Data structure of parsed mo/po files
Character set
The data is always in unicode but the original charset of the file can
be found from the charset
property.
Headers can be found from the headers
object, all keys are lowercase and the value for a key is a string. This value will also be used when compiling.
Translations
Translations can be found from the translations
object which in turn holds context objects for msgctx
. Default context can be found from translations[""]
.
Context objects include all the translations, where msgid
value is the key. The value is an object with the following possible properties:
- msgctx context for this translation, if not present the default context applies
- msgid string to be translated
- msgid_plural the plural form of the original string (might not be present)
- msgstr an array of translations
- comments an object with the following properties:
translator
, reference
, extracted
, flag
, previous
.
Example
{
"charset": "iso-8859-1",
"headers": {
"content-type": "text/plain; charset=iso-8859-1",
"plural-forms": "nplurals=2; plural=(n!=1);"
},
"translations":{
"": {
"": {
"msgid": "",
"msgstr": ["Content-Type: text/plain; charset=iso-8859-1\n..."]
}
},
"another context":{
"example":{
"msgctx": "another context",
"msgid": "%s example",
"msgid_plural": "%s examples",
"msgstr": ["% näide", "%s näidet"],
"comments": {
"translator": "This is regular comment",
"reference": "/path/to/file:123"
}
}
}
}
}
Notice that the structure has both a headers
object and a ""
translation with the header string. When compiling the structure to a mo or a po file, the headers
object is used to define the header. Header string in the ""
translation is just for reference (includes the original unmodified data) but will not be used when compiling. So if you need to add or alter header values, use only the headers
object.
License
MIT