# i18next-conv

> converts .mo and .po files to i18next's json format and vice versa.

Latest version **17.0.0** (published 2026-06-19) · SEE LICENSE IN LICENSE.MD license · 0 weekly downloads

## Install

```sh
npm install i18next-conv
pnpm add i18next-conv
yarn add i18next-conv
bun add i18next-conv
```

Provides the command `i18next-conv`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 17.0.0 |
| Published | 2026-06-19 |
| First published | 2012-09-04 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.MD |
| TypeScript types | none |
| Module format | ESM |
| Node | ^22.13.0 \|\| >=24 |
| Dependencies | 6 |
| Unpacked size | 15.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 203 |
| Author | jamuhl |
| Maintainers | redking, adrai, jamuhl, perrin4869 |
| Keywords | i18next, gettext |

## Links

- npm: https://www.npmjs.com/package/i18next-conv
- Repository: https://github.com/i18next/i18next-gettext-converter
- Homepage: https://github.com/i18next/i18next-gettext-converter#readme
- Issues: https://github.com/i18next/i18next-gettext-converter/issues
- npm.io page: https://npm.io/package/i18next-conv

## Dependencies (6)

- [colorette](https://npm.io/package/colorette.md) ^2.0.20
- [commander](https://npm.io/package/commander.md) ^14.0.3
- [gettext-parser](https://npm.io/package/gettext-parser.md) ^9.0.2
- [p-from-callback](https://npm.io/package/p-from-callback.md) ^3.0.0
- [gettext-converter](https://npm.io/package/gettext-converter.md) ^1.3.2
- [@postalsys/gettext](https://npm.io/package/@postalsys/gettext.md) ^4.1.1

## Alternatives

- [messageformat](https://npm.io/package/messageformat.md) — 329.7K weekly downloads
- [@mintlify/scraping](https://npm.io/package/@mintlify/scraping.md) — 294.8K weekly downloads
- [@mintlify/previewing](https://npm.io/package/@mintlify/previewing.md) — 209.5K weekly downloads
- [@mintlify/prebuild](https://npm.io/package/@mintlify/prebuild.md) — 209.5K weekly downloads
- [@mintlify/link-rot](https://npm.io/package/@mintlify/link-rot.md) — 206.3K weekly downloads

## Recent versions

- 17.0.0 (latest) — 2026-06-19
- 16.0.0 — 2025-11-01
- 15.1.2 — 2025-09-29
- 15.1.1 — 2025-01-06
- 15.1.0 — 2024-12-10
- 15.0.0 — 2024-05-01
- 14.1.0 — 2024-04-08
- 14.0.0 — 2023-06-02
- 13.1.1 — 2023-02-02
- 13.1.0 — 2022-08-15
- 13.0.0 — 2022-06-04
- 12.1.1 — 2022-04-13
- 12.1.0 — 2022-03-07
- 12.0.2 — 2022-02-19
- 12.0.1 — 2022-02-17
- … 58 more at https://npm.io/package/i18next-conv/versions

## README

# i18next-gettext-converter

[![Build Status][build-badge]][build]
[![npm package][npm-badge]][npm]
[![Coverage Status][coveralls-badge]][coveralls]

## Introduction

Project goal is to convert files from gettext to i18next json format and vice versa.

## Installation

1. first install node.js from [nodejs.org](http://nodejs.org/).
2. `npm install i18next-conv -g`

For i18next < 2.0.0 use i18next-conv@1.11.0, for i18next < 3.0.0 use i18next-conv@2.6.1, for i18next < 12.0.0 use i18next-conv@<8.

## Usage

### convert .mo or .po to i18next json

in your console type:


__for help:__

````
i18next-conv -h
````

__to convert a .mo or .po file to i18next json:__

````
i18next-conv -l [locale] -s [sourcePath] -t [targetPath]
````

eg.: i18next-conv -l en -s ./locales/en.po -t ./locales/en/translation.json


_if no target (-t) is specified file will be stored to [sourceDir]/[locale]/translation.json._

__to convert i18next json to a .mo or .po file:__

````
i18next-conv -l [locale] -s [sourcePath] -t [targetPath]
````

eg.: i18next-conv -l en -s ./locales/en.translation.json -t ./locales/en/translation.mo (or .po)

_if no target (-t) is specified file will be stored to [sourceDir]/[locale]/translation.po._


__for utf8-encoded po-files add these lines to your po file:__

````
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
````

It is necessary if you get corrupted output from the command above.

__to filter incoming po-file translations, pass the path to a module that exports a filter function:__

````
i18next-conv -l [locale] -s [sourcePath] -t [targetPath] -f [filterPath]
````

eg.: i18next-conv -l en -s ./locales/en.po -t ./locales/en/translation.json -f ./filter.js

The filter module should export a single function that accepts the gettext object, the locale and a callback
as its arguments. For the full API of the gettext object, check [node-gettext](https://github.com/alexanderwallin/node-gettext).
The function can then add/edit/delete translations, invoking the callback with an error object and the
translation table.

eg.

```javascript
// Delete all keys which do not belong to the frontend
module.exports = function (gt, locale, callback) {
  const clientSideSource = '/frontend/';
  const domain = 'messages';
  const translations = gt.catalogs[locale][domain].translations;
  gt.setLocale(locale); // Needed for when getComment is called

  Object.keys(translations).forEach(ctxt => {
    Object.keys(translations[ctxt]).forEach(key => {
      const comment = gt.getComment('messages', ctxt, key);
      if (comment) {
        if (comment.reference && comment.reference.indexOf(clientSideSource) === -1) {
          delete translations[ctxt][key];
        }
      }
    });
  });

  callback(null, translations);
};
```

## Options

```js
program
.version(i18nextConv.version)
.option('-b, --base [path]', 'Specify path for the base language file. only take effect with -K option', '')
.option('-f, --filter <path>', 'Specify path to gettext filter')
.option('-l, --language <locale>', 'Specify the language code, eg. \'en\'')
.option('-p, --pot', 'Generate POT file.')
.option('-s, --source <path>', 'Specify path to read from')
.option('-t, --target [path]', 'Specify path to write to', '')
.option('-K, --keyasareference', 'Deal with the reference comment as a key', false)
.option('-k, --keyseparator [path]', 'Specify keyseparator you want to use, defaults to ##', '##')
.option('-P, --plurals <path>', 'Specify path to plural forms definitions')
.option('--project <project>', 'Specify the project-id-version when converting json to gettext')
.option('--quiet', 'Silence output', false)
.option('--gettextDefaultCharset', 'Default charset when parsing gettext files with gettext-parser', 'UTF-8')
.option('--skipUntranslated', 'Skip untranslated keys when converting into json', false)
.option('--splitNewLine', 'Outputs gettext multiline values as json array of strings', false)
.option('--ctxSeparator [sep]', 'Specify the context separator', '_')
.option('--ignorePlurals', 'Do not process the plurals')
.option('--compatibilityJSON <ver>', "Set to 'v4' to generate i18next@21 compatible json files")
.option('--foldLength', 'Specify the character fold length for strings', 76)
.option('--noDate', 'Removes timestamp related lines from output file (POT-Creation-Date and PO-Revision-Date lines)')
.parse(process.argv);
```

## API

This module exposes a few functions to convert json to gettext and gettext to json. It accepts the same options as the cli.

```js
const path = require('path');
const { readFileSync, writeFileSync } = require('fs');
const {
  i18nextToPo,
  i18nextToPot,
  i18nextToMo,
  gettextToI18next,
} = require('i18next-conv');

const source = path.join(__dirname, '../locales/ua-UK/translation.json');
const options = {/* you options here */}

function save(target) {
  return result => {
    writeFileSync(target, result);
  };
}

i18nextToPo('ua-UK', readFileSync(source), options).then(save('../locales/ua-UK/translation.po'));
i18nextToPot('ua-UK', readFileSync(source), options).then(save('../locales/ua-UK/translation.pot'));
i18nextToMo('ua-UK', readFileSync(source), options).then(save('../locales/ua-UK/translation.mo'));

gettextToI18next('ua-UK', readFileSync('../locales/ua-UK/translation.po'), options)
.then(save('../locales/ua-UK/translation.json'));

```


## All credits go to

- [andri9's node-gettext](https://github.com/andris9/node-gettext) for parsing .mo and .po files
- [TJ Holowaychuk's commander.js](https://github.com/visionmedia/commander.js/) for console program

## License

See the [LICENSE](LICENSE.md) file for license rights and limitations.

[build-badge]: https://img.shields.io/github/actions/workflow/status/i18next/i18next-gettext-converter/test.yml?event=push&style=flat-square
[build]: https://github.com/i18next/i18next-gettext-converter/actions

[npm-badge]: https://img.shields.io/npm/v/i18next-conv.svg?style=flat-square
[npm]: https://www.npmjs.org/package/i18next-conv

[coveralls-badge]: https://img.shields.io/coveralls/i18next/i18next-gettext-converter/master.svg?style=flat-square
[coveralls]: https://coveralls.io/r/i18next/i18next-gettext-converter

---
_Source: https://npm.io/package/i18next-conv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._