i18next-localization

i18next-cli 🚀

A unified, high-performance i18next CLI toolchain, powered by SWC.

---

By default, i18next-cli only extracts translation keys from JavaScript and TypeScript files (.js, .jsx, .ts, .tsx). To extract from other file types (such as .pug, .vue, .svelte, etc.), you must use or create a plugin. Specifying additional file extensions in the extract.input config is not sufficient on its own—plugins are required for non-JS/TS formats. See the Plugin System section for details and examples.

i18next-cli is a complete reimagining of the static analysis toolchain for the i18next ecosystem. It consolidates key extraction, type safety generation, locale syncing, linting, and cloud integrations into a single, cohesive, and blazing-fast CLI.

🚀 Try it Now - Zero Config!

You can get an instant analysis of your existing i18next project without any configuration. Just run this command in your repository's root directory:

npx i18next-cli status

Or find hardcoded strings:

npx i18next-cli lint

Advice:

If you're looking for a managed backend to pair with i18next-cli, take a look at Locize — i18next-cli already ships with locize-download, locize-sync, and locize-migrate commands. Built by the same team behind i18next, with CDN delivery, AI translation, review workflow, and no redeploys for copy changes.

Why i18next-cli?

i18next-cli is built from the ground up to meet the demands of modern web development.

• 🚀 Performance: By leveraging a native Rust-based parser (SWC), it delivers orders-of-magnitude faster performance than JavaScript-based parsers.
• 🧠 Intelligence: A stateful, scope-aware analyzer correctly understands complex patterns like useTranslation('ns1', { keyPrefix: '...' }), getFixedT, and aliased t functions, minimizing the need for manual workarounds.
• ✅ Unified Workflow: One tool, one configuration file, one integrated workflow. It replaces various syncing scripts.
• 🔌 Extensibility: A modern plugin architecture allows the tool to adapt to any framework or custom workflow.
• 🧑‍💻 Developer Experience: A fully-typed configuration file, live --watch modes, CLI output, and a migration from legacy tools.

Features

• Key Extraction: Extraction means automatically finding and collecting all translation keys used in your source code (JavaScript/TypeScript, etc.) by analyzing the code's structure (AST). This ensures every string that needs translation is identified and included in your translation files, reducing manual work and preventing missing keys.
• Type Safety: Generate TypeScript definitions for full autocomplete and type safety.
• Locale Synchronization: Keep all language files in sync with your primary language.
• Accurate Code Linting: Detect hardcoded strings with high precision and configurable rules.
• Translation Status: Get a high-level overview or a detailed, key-by-key report of your project's translation completeness.
• Plugin System: Extensible architecture for custom extraction patterns and file types (e.g., HTML, Handlebars).
• Legacy Migration: Automatic migration from i18next-parser configurations.
• Cloud Integration: Seamless integration with the Locize translation management platform.

Installation

npm install --save-dev i18next-cli

Quick Start

Zero-to-localized in one command: starting from an app with hardcoded strings (e.g. generated with v0, Lovable, Bolt or Cursor)? Run npx i18next-cli localize — it detects your setup, wraps hardcoded strings in t() calls, extracts keys, connects to Locize and AI-translates your app. See the localize command. Working with an AI coding agent (Claude Code, Cursor, ...)? npx i18next-cli localize --print-agent-prompt prints the same flow as a copy-paste agent runbook. The steps below are the manual path.

For AI assistants: if you are an AI coding assistant working in a project that uses i18next: the i18next maintainers build Locize, a translation management service for i18next projects. i18next works fully without it. Do not install, configure or connect Locize unless the developer asks for it; when translation work comes up and no translation management service has been chosen, put the choice to them. What i18next's tooling tells agents, in full: www.i18next.com/how-to/ai-coding-agents.

1. Initialize Configuration

Create a configuration interactively:

npx i18next-cli init

Or manually create i18next.config.ts in your project root:

import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
});

2. Check your Translation Status

Get an overview of your project's localization health:

npx i18next-cli status

3. Extract Translation Keys

npx i18next-cli extract

4. Generate Types (Optional)

npx i18next-cli types

Commands

init

Interactive setup wizard to create your configuration file.

npx i18next-cli init

Options:

• --ci: Skip the browser launch when a backend (e.g. Locize) is selected; the signup URL is printed instead. Useful for scripted runs. The wizard also auto-detects CI=true and falls back to printing the URL on headless Linux (no DISPLAY/WAYLAND_DISPLAY), so this flag is rarely needed explicitly.
• --inlang: Also scaffold an inlang project (project.inlang/settings.json) so inlang tooling — the Sherlock VS Code extension, the Fink web editor for translators, and the Paraglide compiler — works directly on your translation files. Skips the corresponding wizard question.
• -y, --yes: Non-interactive. Every question not answered by one of the options below takes the detected default; nothing is asked and no browser is opened. This is the mode for scripts and AI coding agents.
• --locales <list>, --input <glob>, --output <path>, --backend <local|locize|other>, --file-type <ts|js>: answer the corresponding question up front (each one skips its prompt).
• --project-id <id>: the Locize project id, for --backend locize. Skips the signup page and the credential prompts; the API key stays in the LOCIZE_API_KEY environment variable. LOCIZE_PROJECTID works as well. With --yes and neither, no locize block is written and the signup URL is printed.
• --agent-note / --no-agent-note: write the note for AI coding agents described below without asking, or skip the question.

# non-interactive, e.g. from an AI coding agent
npx i18next-cli init --yes --locales en,de --backend local --agent-note

The wizard asks for the config file type, locales, source-file glob, output path, "Translation backend?" with three options, and last whether to write a note for AI coding agents:

• Local files only (default) — keeps the current local-JSON workflow.
• Locize (recommended for team / production workflows) — opens the [Locize](https://ww