\n\n## Features\n\n- Choose your weapon: A CLI, a standalone parser or a stream transform\n- 5 built in lexers: Javascript, JSX, HTML, Handlebars, and TypeScript+tsx\n- Handles VueJS 3.0 (.vue) files\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_zero`, `key_one`, `key_two`, `key_few`, `key_many` and `key_other` as described [here](https://www.i18next.com/translation-function/plurals)\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\n- `9.x` is tested on Node 18, 20 and 22.\n- `8.x` is tested on Node 16, 18 and 20.\n- `7.x` is tested on Node 14, 16 and 18.\n- `6.x` is tested on Node 14 and 16.\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,mjs,json,ts,yaml,yml}).\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- **--fail-on-update**: Exit with an exit code of 1 when translations are updated (for CI purpose)\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\nimport { gulp as i18nextParser } from 'i18next-parser'\n\ngulp.task('i18next', function () {\n gulp\n .src('app/**')\n .pipe(\n new i18nextParser({\n locales: ['en', 'de'],\n output: 'locales/$LOCALE/$NAMESPACE.json',\n })\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\nimport Funnel from 'broccoli-funnel'\nimport { broccoli as i18nextParser } from 'i18next-parser'\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\nexport default i18n\n```\n\n> **Note**: You may need to configure Broccoli to place temporary files (option: tmpdir) within the current working\n> directory as I18next-parser does not traverse down beyond that.\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\nexport default {\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 keys with no value\n // You may also specify a function accepting the locale, namespace, key, and value 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 // You may either specify a boolean to keep or discard all removed keys.\n // You may also specify an array of patterns: the keys from the catalog that are no long in the code but match one of the patterns will be kept.\n // The patterns are applied to the full key including the namespace, the parent keys and the separators.\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 // If you don't want to generate keys for plurals (for example, in case you are using ICU format), set `pluralSeparator: false`.\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. Can also be a [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#parameters)\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 failOnUpdate: false,\n // Exit with an exit code of 1 when translations are updated (for CI purpose)\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 //\n // - ${defaultValue} is the default value you set in your translation function.\n // - ${filePaths} will be expanded to an array that contains the absolute\n // file paths where the translations originated in, in case e.g., you need\n // to provide translators with context\n //\n // Any other custom property will be automatically extracted from the 2nd\n // argument of your `t()` function or tOptions in \n //\n // Example:\n // For `t('my-key', {maxLength: 150, defaultValue: 'Hello'})` in\n // /path/to/your/file.js,\n //\n // Using the following customValueTemplate:\n //\n // customValueTemplate: {\n // message: \"${defaultValue}\",\n // description: \"${maxLength}\",\n // paths: \"${filePaths}\",\n // }\n //\n // Will result in the following item being extracted:\n //\n // \"my-key\": {\n // \"message\": \"Hello\",\n // \"description\": 150,\n // \"paths\": [\"/path/to/your/file.js\"]\n // }\n\n resetDefaultValueLocale: null,\n // The locale to compare with default values to determine whether a default value has been changed.\n // If this is set and a default value differs from a translation in the specified locale, all entries\n // for that key across locales are reset to the default value, and existing translations are moved to\n // the `_old` file.\n\n i18nextOptions: null,\n // If you wish to customize options in internally used i18next instance, you can define an object with any\n // configuration property supported by i18next (https://www.i18next.com/overview/configuration-options).\n // { compatibilityJSON: 'v3' } can be used to generate v3 compatible plurals.\n\n yamlOptions: null,\n // If you wish to customize options for yaml output, you can define an object here.\n // Configuration options are here (https://github.com/nodeca/js-yaml#dump-object---options-).\n // Example:\n // {\n // lineWidth: -1,\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 namespaceFunctions: ['useTranslation', 'withTranslation'], // Array of functions to match for namespace\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 componentFunctions: ['Trans'], // Array of components to match\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##### Supporting helper functions in Trans tags\n\nIf you're working with i18next in Typescript, you might be using a helper function to make sure that objects in components pass the typechecker: e.g.,\n\n```tsx\nconst SomeComponent = (props) => (\n \n Visit\n {castAsString({ name: props.name })}'s profile\n {/* Equivalent to, but resolves typechecker errors with */}\n {{ name: props.name }}'s profile\n \n)\n\nfunction castAsString(record: Record): string {\n return record as unknown as string\n}\n```\n\nIn order for the parser to extract variables properly, you can add a list of\nsuch functions to the lexer options:\n\n```\n{\n js: [{\n lexer: 'JsxLexer',\n transIdentityFunctionsToIgnore: ['castAsString']\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\nimport CustomJsLexer from './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` event if the file has a key that is not a string litteral or an option object with a spread operator:\n\n`.pipe( i18next().on('warning', (path, key) => {}) )`\n\nHere is a list of the warnings:\n\n- **Key is not a string literal**: the parser cannot parse variables, only literals. If your code contains something like `t(variable)`, the parser will throw a warning.\n- **Found same keys with different values**: if you use different default values for the same key, you'll get this error. For example, having `t('key', {defaultValue: 'foo'})` and `t('key', {defaultValue: 'bar'})`. The parser will select the latest one.\n- **Found translation key already mapped to a map or parent of new key already mapped to a string**: happens in this kind of situation: `t('parent', {defaultValue: 'foo'})` and `t('parent.child', {defaultValue: 'bar'})`. `parent` is both a translation and an object for `child`.\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