i18next-parser

The lexers option maps file extensions to specific Lexer classes. There are four primary lexers available:

• JavascriptLexer: Used for .js, .mjs, .ts files. It uses the TypeScript compiler to walk the code.
• JsxLexer: Extends the Javascript lexer with support for JSX syntax (used for .jsx, .tsx).
• HTMLLexer: Used for .html and .htm files.
• HandlebarsLexer: Used for .hbs and .handlebars files.

If you use .js files for JSX (common in Create React App), you must override the js lexer to use JsxLexer.

// Example: Enabling JSX parsing in .js files
{
  js: [{ lexer: 'JsxLexer' }],
}

To extract keys from custom function calls (like __('key') or _e('key')), you must configure the functions property within the specific lexer in your configuration.

Configuration Example

{
  lexers: {
    js: [
      {
        lexer: 'JavascriptLexer',
        functions: ['t', 'TAPi18n.__', '__'],
      },
    ]
  }
}

Note: The parser does not match the closing parenthesis to allow for arguments to be passed to the function, and it handles escaped single or double quotes within keys automatically.

You can install i18next-parser globally to use the CLI from anywhere, or locally as a development dependency for Gulp or Broccoli integrations.

# Global installation
yarn global add i18next-parser
npm install -g i18next-parser

# Local development dependency
yarn add -D i18next-parser
npm install --save-dev i18next-parser

To generate separate directories for each locale (e.g., locales/en/, locales/de/), provide an array of locale strings to the locales option.

CLI

Add the locales key to your configuration file:

{
  locales: ['en', 'de', 'sp']
}

Gulp

Pass the locales array within the i18next plugin configuration:

.pipe(i18next({ locales: ['en', 'de', 'sp'] }))

To group all translations into a specific namespace file (e.g., locales/en/my_default_namespace.json), use the namespace option.

CLI

Add the namespace key to your configuration file:

{
  namespace: 'my_default_namespace'
}

Gulp

Pass the namespace string to the i18next plugin:

pipe(i18next({ namespace: 'my_default_namespace' }))

If you use TypeScript generics to define translation keys (e.g., const MyKey T<{count: number}>('my_key')), you can enable parseGenerics and provide a typeMap to ensure the parser correctly identifies these keys.

Configuration Example

{
  lexers: {
    js: [
      {
        lexer: 'JavascriptLexer',
        parseGenerics: true,
        typeMap: { CountType: { count: '' } },
      },
    ]
  }
}

This allows the parser to detect patterns like:

const MyKey T<{count: number}>('my_key');
const MyOtherKey = T<CountType>('my_other_key');

The CLI syntax changed from a positional input:output pattern to using the --output option and glob patterns for filtering. The recursive, directoryFilter, and fileFilter flags were deprecated in favor of passing globs directly.

Old syntax (0.x):

i18next src --recursive --fileFilter '*.hbs,*.js' --directoryFilter '!.git'

New syntax (1.x+):

i18next 'src/**/*.{js,hbs}' '!.git'

You can customize how the parser identifies namespaces and subkeys within a string (e.g., parsing namespace?key_subkey into a nested JSON object). Use namespaceSeparator and keySeparator in your configuration.

CLI

{
  namespaceSeparator: '?',
  keySeparator: '_'
}

Gulp

.pipe(i18next({namespaceSeparator: '?', keySeparator: '_'}))

You can specify where the generated translation files are created using the output option. The parser supports placeholders like $LOCALE and $NAMESPACE to dynamically name files and folders.

Command Line

Use the -o flag or the : syntax:

$ i18next /path/to/file/or/dir -o /translations/$LOCALE/$NAMESPACE.json
$ i18next /path/to/file/or/dir:/translations/$LOCALE/$NAMESPACE.json

Gulp

When using Gulp, ensure you call .dest() to actually write the files to the filesystem:

.pipe(i18next({ output: 'translations/$LOCALE/$NAMESPACE.json' }))