Home

Awesome

gettext-parser ci

Parse and compile gettext po and mo files with node.js, nothing more, nothing less.

Please note: starting with version 3 only latest LTS and latest stable node versions are supported. Use version 2 with older node versions.

Usage

Include the library:

import gettextParser from "gettext-parser";

Parse PO files

Parse a PO file with

gettextParser.po.parse(input[, options]) → Object

Where

Method returns gettext-parser specific translation object (see below)

Example

import { readFileSync } from 'node:fs';
var input = readFileSync('en.po');
var po = gettextParser.po.parse(input);
console.log(po.translations['']); // output translations for the default context

Parse PO as a Stream

PO files can also be parsed from a stream source. After all input is processed the parser emits a single 'data' event which contains the parsed translation object.

gettextParser.po.createParseStream([options][, transformOptions]) → Transform Stream

Where

Example

import { createReadStream } from 'node:fs';
var input = createReadStream('en.po');
var po = gettextParser.po.createParseStream();
input.pipe(po);
po.on('data', function(data){
    console.log(data.translations['']); // output translations for the default context
});

Compile PO from a translation object

If you have a translation object you can convert this to a valid PO file with

gettextParser.po.compile(data[, options]) → Buffer

Where

Example

import { writeFileSync } from 'node:fs';
var data = {
    ...
};
var output = gettextParser.po.compile(data);
writeFileSync('filename.po', output);

Parse MO files

Parse a MO file with

gettextParser.mo.parse(input[, defaultCharset]) → Object

Where

Method returns gettext-parser specific translation object (see below)

Example

import { readFileSync } from 'node:fs';
var input = readFileSync('en.mo');
var mo = gettextParser.mo.parse(input);
console.log(mo.translations['']); // output translations for the default context

Compile MO from a translation object

If you have a translation object you can convert this to a valid MO file with

gettextParser.mo.compile(data) → Buffer

Where

Example

import { writeFileSync } from 'node:fs';
var data = {
    ...
};
var output = gettextParser.mo.compile(data);
writeFileSync('filename.mo', output);

Notes

Overriding charset

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.

ICONV support

By default gettext-parser uses pure JS iconv-lite for encoding and decoding non UTF-8 charsets. If you need to support more complex encodings that are not supported by iconv-lite, you need to add iconv as an additional dependency for your project (gettext-parser will detect if it is available and tries to use it instead of iconv-lite).

Data structure of parsed mo/po files

Character set

Parsed data is always in unicode but the original charset of the file can be found from the charset property. This value is also used when compiling translations to a mo or po file.

Headers

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 msgctxt. 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:

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": {
      "%s example": {
        "msgctxt": "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.

If you need to convert gettext-parser formatted translation object to something else, eg. for jed, check out po2json.

License

MIT