\n\n## Features\n\n- Choose your weapon: A CLI, a standalone parser or a stream transform\n- 6 built in lexers: Javascript, JSX, HTML, Handlebars, TypeScript+tsx and Vue\n- Creates one catalog file per locale and per namespace\n- Backs up the old keys your code doesn't use anymore in `namespace_old.json` catalog\n- Restores keys from the `_old` file if the one in the translation file is empty\n- Parses comments for static keys to support dynamic key translations.\n- Supports i18next features:\n - **Context**: keys of the form `key_context`\n - **Plural**: keys of the form `key_plural` and `key_0`, `key_1` as described [here](https://www.i18next.com/translation-function/plurals)\n- Tested on Node 10+. If you need support for 6 and 8, look at the `1.0.x` versions.\n\n## Versions\n\nYou can find information about major releases on the [dedicated page](https://github.com/i18next/i18next-parser/releases). The [migration documentation](docs/migration.md) will help you figure out the breaking changes between versions.\n\nFor legacy users on `0.x`, the code has since been entirely rewritten and there is a dedicated [branch](https://github.com/i18next/i18next-parser/tree/0.x.x) for it. You are highly encouraged to upgrade!\n\n## Usage\n\n### CLI\n\nYou can use the CLI with the package installed locally but if you want to use it from anywhere, you better install it globally:\n\n```\nyarn global add i18next-parser\nnpm install -g i18next-parser\ni18next 'app/**/*.{js,hbs}' 'lib/**/*.{js,hbs}' [-oc]\n```\n\nMultiple globbing patterns are supported to specify complex file selections. You can learn how to write globs [here](https://github.com/isaacs/node-glob). Note that glob must be wrapped with single quotes when passed as arguments.\n\n**IMPORTANT NOTE**: If you pass the globs as CLI argument, they must be relative to where you run the command (aka relative to `process.cwd()`). If you pass the globs via the `input` option of the config file, they must be relative to the config file.\n\n- **-c, --config **: Path to the config file (default: i18next-parser.config.js).\n- **-o, --output **: Path to the output directory (default: locales/$LOCALE/$NAMESPACE.json).\n- **-s, --silent**: Disable logging to stdout.\n- **--fail-on-warnings**: Exit with an exit code of 1 on warnings\n\n### Gulp\n\nSave the package to your devDependencies:\n\n```\nyarn add -D i18next-parser\nnpm install --save-dev i18next-parser\n```\n\n[Gulp](http://gulpjs.com/) defines itself as the streaming build system. Put simply, it is like Grunt, but performant and elegant.\n\n```javascript\nconst i18nextParser = require('i18next-parser').gulp;\n\ngulp.task('i18next', function() {\n gulp.src('app/**')\n .pipe(new i18nextParser({\n locales: ['en', 'de'],\n output: 'locales/$LOCALE/$NAMESPACE.json'\n }))\n .pipe(gulp.dest('./'));\n});\n```\n\n**IMPORTANT**: `output` is required to know where to read the catalog from. You might think that `gulp.dest()` is enough though it does not inform the transform where to read the existing catalog from.\n\n### Broccoli\n\nSave the package to your devDependencies:\n\n```\nyarn add -D i18next-parser\nnpm install --save-dev i18next-parser\n```\n\n[Broccoli.js](https://github.com/broccolijs/broccoli) defines itself as a fast, reliable asset pipeline, supporting constant-time rebuilds and compact build definitions.\n\n```javascript\nconst Funnel = require('broccoli-funnel')\nconst i18nextParser = require('i18next-parser').broccoli\n\nconst appRoot = 'broccoli'\n\nlet i18n = new Funnel(appRoot, {\n files: ['handlebars.hbs', 'javascript.js'],\n annotation: 'i18next-parser'\n})\n\ni18n = new i18nextParser([i18n], {\n output: 'broccoli/locales/$LOCALE/$NAMESPACE.json'\n})\n\nmodule.exports = i18n\n```\n\n## Options\n\nUsing a config file gives you fine-grained control over how i18next-parser treats your files. Here's an example config showing all config options with their defaults.\n\n```js\n// i18next-parser.config.js\n\nmodule.exports = {\n contextSeparator: '_',\n // Key separator used in your translation keys\n\n createOldCatalogs: true,\n // Save the \\_old files\n\n defaultNamespace: 'translation',\n // Default namespace used in your i18next config\n\n defaultValue: '',\n // Default value to give to empty keys\n // You may also specify a function accepting the locale, namespace, and key as arguments\n\n indentation: 2,\n // Indentation of the catalog files\n\n keepRemoved: false,\n // Keep keys from the catalog that are no longer in code\n\n keySeparator: '.',\n // Key separator used in your translation keys\n // If you want to use plain english keys, separators such as `.` and `:` will conflict. You might want to set `keySeparator: false` and `namespaceSeparator: false`. That way, `t('Status: Loading...')` will not think that there are a namespace and three separator dots for instance.\n\n // see below for more details\n lexers: {\n hbs: ['HandlebarsLexer'],\n handlebars: ['HandlebarsLexer'],\n\n htm: ['HTMLLexer'],\n html: ['HTMLLexer'],\n\n mjs: ['JavascriptLexer'],\n js: ['JavascriptLexer'], // if you're writing jsx inside .js files, change this to JsxLexer\n ts: ['JavascriptLexer'],\n jsx: ['JsxLexer'],\n tsx: ['JsxLexer'],\n\n default: ['JavascriptLexer']\n },\n\n lineEnding: 'auto',\n // Control the line ending. See options at https://github.com/ryanve/eol\n\n locales: ['en', 'fr'],\n // An array of the locales in your applications\n\n namespaceSeparator: ':',\n // Namespace separator used in your translation keys\n // If you want to use plain english keys, separators such as `.` and `:` will conflict. You might want to set `keySeparator: false` and `namespaceSeparator: false`. That way, `t('Status: Loading...')` will not think that there are a namespace and three separator dots for instance.\n\n output: 'locales/$LOCALE/$NAMESPACE.json',\n // Supports $LOCALE and $NAMESPACE injection\n // Supports JSON (.json) and YAML (.yml) file formats\n // Where to write the locale files relative to process.cwd()\n\n pluralSeparator: '_',\n // Plural separator used in your translation keys\n // If you want to use plain english keys, separators such as `_` might conflict. You might want to set `pluralSeparator` to a different string that does not occur in your keys.\n\n input: undefined,\n // An array of globs that describe where to look for source files\n // relative to the location of the configuration file\n\n sort: false,\n // Whether or not to sort the catalog\n\n skipDefaultValues: false,\n // Whether to ignore default values\n // You may also specify a function accepting the locale and namespace as arguments\n\n useKeysAsDefaultValue: false,\n // Whether to use the keys as the default value; ex. \"Hello\": \"Hello\", \"World\": \"World\"\n // This option takes precedence over the `defaultValue` and `skipDefaultValues` options\n // You may also specify a function accepting the locale and namespace as arguments\n\n verbose: false,\n // Display info about the parsing including some stats\n\n failOnWarnings: false,\n // Exit with an exit code of 1 on warnings\n\n customValueTemplate: null\n // If you wish to customize the value output the value as an object, you can set your own format.\n // ${defaultValue} is the default value you set in your translation function.\n // Any other custom property will be automatically extracted.\n //\n // Example:\n // {\n // message: \"${defaultValue}\",\n // description: \"${maxLength}\", // t('my-key', {maxLength: 150})\n // }\n}\n```\n\n### Lexers\n\nThe `lexers` option let you configure which Lexer to use for which extension. Here is the default:\n\nNote the presence of a `default` which will catch any extension that is not listed.\nThere are 4 lexers available: `HandlebarsLexer`, `HTMLLexer`, `JavascriptLexer` and\n`JsxLexer`. Each has configurations of its own. Typescript is supported via `JavascriptLexer` and `JsxLexer`.\nIf you need to change the defaults, you can do it like so:\n\n#### Javascript\n\nThe Javascript lexer uses [Typescript compiler](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) to walk through your code and extract translation functions.\n\nThe default configuration is below:\n\n```js\n{\n // JavascriptLexer default config (js, mjs)\n js: [{\n lexer: 'JavascriptLexer',\n functions: ['t'], // Array of functions to match\n }],\n}\n```\n\n#### Jsx\n\nThe JSX lexer builds off of the Javascript lexer and extends it with support for JSX syntax.\n\nDefault configuration:\n\n```js\n{\n // JsxLexer default config (jsx)\n // JsxLexer can take all the options of the JavascriptLexer plus the following\n jsx: [{\n lexer: 'JsxLexer',\n attr: 'i18nKey', // Attribute for the keys\n }],\n}\n```\n\nIf your JSX files have `.js` extension (e.g. create-react-app projects) you should override the default `js` lexer with `JsxLexer` to enable jsx parsing from js files:\n\n```js\n{\n js: [{\n lexer: 'JsxLexer'\n }],\n}\n```\n\n#### Ts(x)\n\nTypescript is supported via Javascript and Jsx lexers. If you are using Javascript syntax (e.g. with React), follow the steps in Jsx section, otherwise Javascript section.\n\n#### Handlebars\n\n```js\n{\n // HandlebarsLexer default config (hbs, handlebars)\n handlebars: [\n {\n lexer: 'HandlebarsLexer',\n functions: ['t'] // Array of functions to match\n }\n ]\n}\n```\n\n#### Html\n\n```js\n{\n // HtmlLexer default config (htm, html)\n html: [{\n lexer: 'HtmlLexer',\n attr: 'data-i18n' // Attribute for the keys\n optionAttr: 'data-i18n-options' // Attribute for the options\n }]\n}\n```\n\n#### Custom lexers\n\nYou can provide function instead of string as a custom lexer.\n\n```js\nconst CustomJsLexer = require('./CustomJsLexer');\n\n// ...\n{\n js: [CustomJsLexer],\n jsx: [{\n lexer: CustomJsLexer,\n customOption: true // Custom attribute passed to CustomJsLexer class constructor\n }]\n}\n// ...\n```\n\n### Caveats\n\nWhile i18next extracts translation keys in runtime, i18next-parser doesn't run the code, so it can't interpolate values in these expressions:\n\n```\nt(key)\nt('key' + id)\nt(`key${id}`)\n```\n\nAs a workaround you should specify possible static values in comments anywhere in your file:\n\n```\n// t('key_1')\n// t('key_2')\nt(key)\n\n/*\nt('key1')\nt('key2')\n*/\nt('key' + id)\n```\n\n## Events\n\nThe transform emits a `reading` event for each file it parses:\n\n`.pipe( i18next().on('reading', (file) => {}) )`\n\nThe transform emits a `error:json` event if the JSON.parse on json files fail:\n\n`.pipe( i18next().on('error:json', (path, error) => {}) )`\n\nThe transform emits a `warning:variable` event if the file has a key that contains a variable:\n\n`.pipe( i18next().on('warning:variable', (path, key) => {}) )`\n\n## Contribute\n\nAny contribution is welcome. Please [read the guidelines](docs/development.md) first.\n\nThanks a lot to all the previous [contributors](https://github.com/i18next/i18next-parser/graphs/contributors).\n\nIf you use this package and like it, supporting me on [Patreon](https://www.patreon.com/karelledru) is another great way to contribute!\n\n
![\"Become](\"https://c5.patreon.com/external/logo/become_a_patron_button.png\"){kind=logo}
\n \n![](\"https://raw.githubusercontent.com/i18next/i18next/master/assets/locize_sponsor_240.gif\")
\n \n