{"id":21241691,"url":"https://github.com/smhg/gettext-parser","last_synced_at":"2025-05-15T18:08:40.870Z","repository":{"id":477046,"uuid":"11481087","full_name":"smhg/gettext-parser","owner":"smhg","description":"Parse and compile gettext po and mo files, nothing more, nothing less","archived":false,"fork":false,"pushed_at":"2024-05-13T10:29:26.000Z","size":384,"stargazers_count":157,"open_issues_count":11,"forks_count":42,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-05-22T00:04:03.286Z","etag":null,"topics":["gettext"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smhg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-07-17T16:21:04.000Z","updated_at":"2024-06-18T12:28:35.523Z","dependencies_parsed_at":"2024-05-12T20:21:13.521Z","dependency_job_id":"338ab75f-223e-4b34-bd0a-58a96b5bd0b8","html_url":"https://github.com/smhg/gettext-parser","commit_stats":{"total_commits":188,"total_committers":24,"mean_commits":7.833333333333333,"dds":0.5,"last_synced_commit":"dae6db73a3099e209106d3e5d31ef1e2cd16a122"},"previous_names":["andris9/gettext-parser"],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smhg%2Fgettext-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smhg%2Fgettext-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smhg%2Fgettext-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smhg%2Fgettext-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smhg","download_url":"https://codeload.github.com/smhg/gettext-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744332,"owners_count":20988783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gettext"],"created_at":"2024-11-21T00:56:41.429Z","updated_at":"2025-04-07T23:08:05.950Z","avatar_url":"https://github.com/smhg.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"gettext-parser [![ci](https://github.com/smhg/gettext-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/smhg/gettext-parser/actions/workflows/ci.yml)\n==============\n\nParse and compile gettext *po* and *mo* files with node.js, nothing more, nothing less.\n\n\u003e *Please note:* starting with version 3 only latest LTS and latest stable node versions are supported. **Use version 2 with older node versions.**\n\n## Usage\n\nInclude the library:\n\n    import gettextParser from \"gettext-parser\";\n\n### Parse PO files\n\nParse a PO file with\n\n    gettextParser.po.parse(input[, options]) → Object\n\nWhere\n\n  * **input** is a *po* file as a Buffer or an unicode string. Charset is converted to unicode from other encodings only if the input is a Buffer, otherwise the charset information is discarded\n  * **options** is an optional object with the following optional properties:\n    * **defaultCharset** is the charset to use if charset is not defined or is the default `\"CHARSET\"` (applies only if *input* is a Buffer)\n    * **validation** is a flag to turn on PO source file validation. The validation makes sure that:\n\n      * there is exactly zero or one `msgid_plural` definition per translation entry; a `Multiple msgid_plural error` error gets thrown otherwise.\n      * there are no duplicate entries with exact `msgid` values; a `Duplicate msgid error` error gets thrown otherwise.\n      * the number of plural forms matches exactly the number from `nplurals` defined in `Plural-Forms` header for entries that have plural forms; a `Plural forms range error` error gets thrown otherwise.\n      * the number of `msgstr` matches exacty the one (if `msgid_plural` is not defined) or the number from `nplurals` (if `msgid_plural` is defined); a `Translation string range error` error gets thrown otherwise.\n\nMethod returns gettext-parser specific translation object (see below)\n\n**Example**\n\n```javascript\nimport { readFileSync } from 'node:fs';\nvar input = readFileSync('en.po');\nvar po = gettextParser.po.parse(input);\nconsole.log(po.translations['']); // output translations for the default context\n```\n\n### Parse PO as a Stream\n\nPO 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.\n\n    gettextParser.po.createParseStream([options][, transformOptions]) → Transform Stream\n\nWhere\n\n  * **options** is an optional object, same as in `parse`. See [Parse PO files](#parse-po-files) section for details.\n  * **transformOptions** are the standard stream options.\n\n**Example**\n\n```javascript\nimport { createReadStream } from 'node:fs';\nvar input = createReadStream('en.po');\nvar po = gettextParser.po.createParseStream();\ninput.pipe(po);\npo.on('data', function(data){\n    console.log(data.translations['']); // output translations for the default context\n});\n```\n\n### Compile PO from a translation object\n\nIf you have a translation object you can convert this to a valid PO file with\n\n    gettextParser.po.compile(data[, options]) → Buffer\n\nWhere\n\n  * **data** is a translation object either got from parsing a PO/MO file or composed by other means\n  * **options** is a configuration object with possible values\n    * **foldLength** is the length at which to fold message strings into newlines (default: 76). Set to 0 or false to disable folding.\n    * **sort** (boolean|Function) - (default `false`) if `true`, entries will be sorted by msgid in the resulting .po(.pot) file.\n      If a comparator function is provided, that function will be used to sort entries in the output. The function is called with two arguments, each of which is a single message entry with the structure described below. The function should follow the standard rules for functions passed to `Array.sort()`: return `0` if the entries are interchangeable in sort order; return a number less than 0 if the first entry should come before the second one; and return a number greater than 0 if the second entry should come before the first one.\n    * **escapeCharacters** (boolean) - (default `true`) if `false`, will skip escape newlines and quotes characters functionality.\n\n**Example**\n\n```javascript\nimport { writeFileSync } from 'node:fs';\nvar data = {\n    ...\n};\nvar output = gettextParser.po.compile(data);\nwriteFileSync('filename.po', output);\n```\n\n### \n\n### Parse MO files\n\nParse a MO file with\n\n    gettextParser.mo.parse(input[, defaultCharset]) → Object\n\nWhere\n\n  * **input** is a *mo* file as a Buffer\n  * **defaultCharset** is the charset to use if charset is not defined or is the default `\"CHARSET\"`\n\nMethod returns gettext-parser specific translation object (see below)\n\n**Example**\n\n```javascript\nimport { readFileSync } from 'node:fs';\nvar input = readFileSync('en.mo');\nvar mo = gettextParser.mo.parse(input);\nconsole.log(mo.translations['']); // output translations for the default context\n```\n\n### Compile MO from a translation object\n\nIf you have a translation object you can convert this to a valid MO file with\n\n    gettextParser.mo.compile(data) → Buffer\n\nWhere\n\n  * **data** is a translation object either got from parsing a PO/MO file or composed by other means\n\n**Example**\n\n```javascript\nimport { writeFileSync } from 'node:fs';\nvar data = {\n    ...\n};\nvar output = gettextParser.mo.compile(data);\nwriteFileSync('filename.mo', output);\n```\n\n### Notes\n\n#### Overriding charset\n\nIf 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).\n\n```javascript\nvar obj = gettextParser.po.parse(inputBuf);\nobj.charset = \"windows-1257\";\noutputBuf = gettextParser.po.compile(obj);\n```\n\nHeaders for the output are modified to match the updated charset.\n\n#### ICONV support\n\nBy default *gettext-parser* uses pure JS [iconv-lite](https://github.com/ashtuchkin/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](https://github.com/bnoordhuis/node-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*).\n\n## Data structure of parsed mo/po files\n\n### Character set\n\nParsed data is always in unicode but the original charset of the file can\nbe found from the `charset` property. This value is also used when compiling translations\nto a *mo* or *po* file.\n\n### Headers\n\nHeaders 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.\n\n### Translations\n\nTranslations can be found from the `translations` object which in turn holds context objects for `msgctxt`. Default context can be found from `translations[\"\"]`.\n\nContext objects include all the translations, where `msgid` value is the key. The value is an object with the following possible properties:\n\n  * **msgctxt** context for this translation, if not present the default context applies\n  * **msgid** string to be translated\n  * **msgid_plural** the plural form of the original string (might not be present)\n  * **msgstr** an array of translations\n  * **comments** an object with the following properties: `translator`, `reference`, `extracted`, `flag`, `previous`.\n\nExample\n\n```json\n{\n  \"charset\": \"iso-8859-1\",\n\n  \"headers\": {\n    \"content-type\": \"text/plain; charset=iso-8859-1\",\n    \"plural-forms\": \"nplurals=2; plural=(n!=1);\"\n  },\n\n  \"translations\": {\n    \"\": {\n      \"\": {\n        \"msgid\": \"\",\n        \"msgstr\": [\"Content-Type: text/plain; charset=iso-8859-1\\n...\"]\n      }\n    },\n    \"another context\": {\n      \"%s example\": {\n        \"msgctxt\": \"another context\",\n        \"msgid\": \"%s example\",\n        \"msgid_plural\": \"%s examples\",\n        \"msgstr\": [\"% näide\", \"%s näidet\"],\n        \"comments\": {\n          \"translator\": \"This is regular comment\",\n          \"reference\": \"/path/to/file:123\"\n        }\n      }\n    }\n  }\n}\n```\n\nNotice 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.\n\nIf you need to convert *gettext-parser* formatted translation object to something else, eg. for *jed*, check out [po2json](https://github.com/mikeedwards/po2json).\n\n## License\n\n**MIT**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmhg%2Fgettext-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmhg%2Fgettext-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmhg%2Fgettext-parser/lists"}