i18next CLI

1.56.2 · active · verified Wed Apr 22

i18next-cli is a unified, high-performance command-line interface tool for the i18next internationalization ecosystem, currently at version 1.56.2. It leverages the Rust-based SWC parser for rapid static analysis, providing features such as automatic translation key extraction from JavaScript and TypeScript files, generation of TypeScript type definitions for improved developer experience, synchronization of locale files, and intelligent linting to detect hardcoded strings. The tool is designed to consolidate various i18next-related static analysis tasks into a single, cohesive workflow, replacing disparate scripts and older tools like `i18next-parser`. It also features a modern plugin architecture for extensibility to custom file types and workflows, and offers seamless integration with translation management platforms like Locize.

Common errors

```
Error: Node.js version is too old. i18next-cli requires Node.js >= 22.
```
cause Attempting to run i18next-cli with an unsupported Node.js version.

fix Update your Node.js environment to version 22 or newer. For example, using nvm: `nvm install 22 && nvm use 22`.
```
i18next-cli: No input files found for extraction. Please check your 'extract.input' configuration.
```
cause The `extract.input` configuration array does not correctly point to source files, or the specified files do not exist.

fix Verify that the glob patterns in `i18next.config.ts` under `extract.input` correctly match your project's source files. Ensure file paths are relative to the config file's location.
```
i18next-cli: Could not extract keys from 'path/to/my-component.vue'. Only JS/TS files are supported by default.
```
cause Attempting to extract translation keys from a non-JavaScript/TypeScript file type without a specific plugin.

fix Install or create a `i18next-cli` plugin for the specific file type (e.g., '.vue' files) you wish to extract keys from. Consult the 'Plugin System' section in the documentation.

Warnings

breaking i18next-cli is a 'complete reimagining' of the i18next static analysis toolchain. Users migrating from older tools like `i18next-parser` or custom scripts will need to adopt a new configuration format and workflow. While it offers migration helpers, direct compatibility is not guaranteed.
Fix: Utilize the `npx i18next-cli init` command to create a new configuration file, or refer to the `i18next.config.ts` documentation for the new format. Review existing i18next-parser configurations to translate them to the new `i18next-cli` config structure.
gotcha Key extraction is limited by default to JavaScript and TypeScript files (.js, .jsx, .ts, .tsx). Simply adding other file extensions (e.g., .vue, .svelte, .pug) to the `extract.input` configuration array will NOT enable extraction from those formats.
Fix: For non-JavaScript/TypeScript file types, a dedicated plugin is required. Check the documentation for available plugins or create a custom plugin to handle specific templating languages or frameworks.
breaking The package requires Node.js version 22 or higher. Older Node.js versions are not supported and will lead to execution failures.
Fix: Upgrade your Node.js environment to version 22 or newer. Use a Node Version Manager (NVM) like `nvm install 22 && nvm use 22` to manage multiple Node.js versions.

Install

npm install i18next-cli npm
yarn add i18next-cli yarn
pnpm add i18next-cli pnpm

Imports

defineConfig
wrong:
```
const defineConfig = require('i18next-cli').defineConfig;
```
correct:
```
import { defineConfig } from 'i18next-cli';
```
Used for configuring the i18next-cli in an `i18next.config.ts` file. Primarily an ESM pattern for configuration.
CLI usage
wrong:
```
import { run } from 'i18next-cli'; // Incorrect library usage
```
correct:
```
npx i18next-cli <command>
```
The package is primarily a CLI tool and is typically invoked via `npx` or a script defined in `package.json`.

Quickstart

Installs the CLI, sets up a basic TypeScript configuration file, and then demonstrates checking translation status and extracting keys.

npm install --save-dev i18next-cli

// Create i18next.config.ts in your project root
// This enables TypeScript support and robust configuration.
// For zero-config quick testing, skip this step and run 'npx i18next-cli status'.
import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
  // For more complex setups, e.g., with React components in 'components'
  // and pages in 'pages', you might extend the input array.
  // lint: { ... }, // Add linting rules
  // sync: { ... }, // Add synchronization options
});

// Check the current translation status of your project
npx i18next-cli status

// Extract translation keys based on your configuration
npx i18next-cli extract

view raw JSON →