@i18nexus/cli

A command line interface for accessing and managing translations through the i18nexus API

This package was previously published as i18nexus-cli. New installs should use @i18nexus/cli. The command remains i18nexus.

New to i18nexus?

i18nexus is a translation management web application designed for use with next-intl, i18next, and react-intl.

Start with the Getting Started guide for a quick overview of how i18nexus works and how to set up your app.

For deeper i18n tutorials:

• next-intl for Next.js App Router Walkthrough
• react-i18next for Next.js App Router Walkthrough
• next-i18next for Next.js Pages Router Walkthrough
• react-i18next Walkthrough
• react-intl Walkthrough

CLI and MCP

i18nexus also provides an official MCP server for Claude, Codex, and other AI coding assistants.

Most teams use the CLI and MCP together. Use the MCP when you want an AI coding assistant to add, update, search, or manage source strings in i18nexus while it edits your app. The MCP lets agents work through i18nexus as the source of truth instead of editing generated local translation JSON directly.

Use this CLI to initialize a project, import existing translation JSON, listen for i18nexus changes during local development, pull generated translation files, and run direct terminal commands.

i18nexus init can set up the MCP for your project automatically.

Installation

Most common setup

For app projects, install the CLI as a development dependency:

npm install --save-dev @i18nexus/cli

This is the most common setup for users who primarily want to use the CLI for pull and listen inside an app project.

Global installation

Install the CLI globally only when you want to run specific i18nexus commands directly from your terminal:

npm install -g @i18nexus/cli

Environment Variables

The commands below have options that can be set with environment variables. Since the majority of our users are using this package in the context of their web application, this package will load the .env file in the current working directory to check for i18nexus variables. If you would prefer not to load your .env file, you can run export I18NEXUS_NO_DOT_ENV=true.

First-time setup

i18nexus init

This command creates an i18nexus project for your app and sets up your local workflow to keep translations synced automatically.

What it does:

• Opens your browser to authenticate
• Creates your project, languages, and namespaces in i18nexus
• Prints the environment variables you need
• Offers to add local, gitignored project-scoped MCP config for Claude and Codex
• Optionally updates your package.json scripts to automatically keep translations in sync

Downloading your translations

i18nexus pull -k <PROJECT_API_KEY>

The above snippet will download all of your latest translations to the default path for your project's i18n library. Your translation files will be downloaded in a file structure based on that library's convention.

Default download path:

If your i18nexus project is set to i18next:

.
└── public
    └── locales
        ├── en
        |   └── common.json
        └── de
            └── common.json

If your i18nexus project is set to next-intl:

.
└── messages
    └── en.json
    └── de.json

If your i18nexus project is set to react-intl:

.
└── src
    └── messages
        ├── en
        |   └── common.json
        └── de
            └── common.json

If your i18nexus project is set to react-intl and a src directory does not exist:

.
└── messages
    ├── en
    |   └── common.json
    └── de
        └── common.json

If you wish to download your files to a different directory, you can use the --path option to specify your download destination. See all options below:

Options

| Option | Default value | | ------------------- | ------------- | | --api-key or -k | | | --path or -p | (See above) | | --ver or -v | latest | | --confirmed | false | | --clean | false | | --compact | false |

Notes

--api-key Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

--path The path to the destination folder in which translation files will be downloaded

--ver The version of your project's translations to be downloaded (Can also be set using environment variable I18NEXUS_VERSION)

--confirmed Downloads only translations that have been confirmed in i18nexus

--clean Before download, clears your destination folder specified in --path. As a safety precaution, this only deletes folders with names that match a simple language code regex. You should still ensure you are not storing any files in your destination folder that you do not want deleted.

--compact Output JSON without extra whitespace (default is pretty-printed)

Listening for live translation updates

i18nexus listen

i18nexus listen -k <PROJECT_API_KEY>

This command opens a WebSocket connection from your local environment to the i18nexus servers to receive real-time updates whenever strings are added, updated, or deleted in your project.

When changes occur, your local JSON files are automatically refreshed to stay in sync.

i18nexus init can set this up for you automatically. If you prefer to configure it yourself, many developers run this alongside their development server. For example, in a Next.js project, you can do the following in your package.json using concurrently:

"scripts": {
    "dev": "concurrently --raw \"next dev --turbo\" \"i18nexus listen\"",
    "build": "i18nexus pull && next build",
    "start": "i18nexus pull && next start",
    "lint": "next lint"
}

Options

| Option | Required? | Default | | ------------------- | --------- | ----------------------- | | --api-key or -k | ✔ | | | --path or -p | | See pull default path | | --compact | | false |

Notes

--api-key
Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

--path The path to the destination folder in which translation files will be downloaded

--compact Output JSON without extra whitespace (default is pretty-printed)

Viewing project metadata

i18nexus project

i18nexus project -k <PROJECT_API_KEY>

The above snippet prints your i18nexus project metadata as formatted JSON. This is useful for checking your project title, base language, i18n library, enabled namespaces, string AI context setting, and configured languages from the command line.

Example output:

{
  "id": 123,
  "title": "My Project",
  "library": "i18next",
  "language": "en",
  "languages": ["de"],
  "use_namespaces": true,
  "use_description_as_ai_context": true,
  "namespaces": ["common", "auth"]
}

Use description as AI context is a setting in your i18nexus dashboard. By default, it is on, which means the description field is also used as AI context.

If you turn it off, you get two different fields:

• description, which is used for internal team notes and not sent to AI
• ai_instructions, which are sent to AI

Options

| Option | Required? | | ------------------- | --------- | | --api-key or -k | ✔ |

Notes

--api-key Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

Personal Access Tokens

The following commands require a Personal Access Token (PAT) because they write data to your i18nexus project. PATs are created in your i18nexus account dashboard.

REMEMBER: Keep these tokens a secret and do NOT publish them to any public code repositories such as Github. They should never be client facing. Treat each token as if it is your i18nexus password.

Adding new strings

i18nexus add-string or i18nexus a

i18nexus a -K 'welcome_msg' -v 'Welcome to my app!' -ns 'common' -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>

The above snippet will create a new string in your i18nexus project.

Translations for the string will be automatically generated and machine translated for all of your project's languages, just as if you added the string manually in the i18nexus web application.

If you want to add multiple strings at once, see i18nexus bulk-add-strings and i18nexus import.

Options

| Option | Required? | | ---------------------------- | ------------- | | --api-key or -k | ✔ | | --pat or -t | ✔ | | --key or -K | ✔ | | --value or -v | ✔ | | --namespace or -ns | Conditionally | | --description or -d | | | --ai-instructions or -ai | |

Notes

--api-key Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

--pat A personal access token that you have generated in your i18nexus account (Can also be set using environment variable I18NEXUS_PERSONAL_ACCESS_TOKEN)

--namespace The namespace in which to create the string. Omit this if your project does not use namespaces. Only required if your project uses namespaces and has more than one namespace.

--key The key of the string to create

--value The value of the string to create

--description Description about the string to create. When Use description as AI context is on, this is also sent to AI during translation.

--ai-instructions String-level AI translation context. Only use this when Use description as AI context is off.

Updating existing strings

i18nexus update-string <namespace:key> or i18nexus u <namespace:key>

i18nexus u common:welcome_msg -v 'Welcome' -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>

The above snippet will update the value of the string with key welcome_msg in your common namespace to Welcome.

The required argument is the namespace and the key of the string you wish to update, joined with a colon (":"). If your project does not use namespaces or only has one namespace, only the key is necessary.

You can then update the key, value, description, and/or namespace by using the command options:

Options

| Option | Required? | | ---------------------------- | --------- | | --api-key or -k | ✔ | | --pat or -t | ✔ | | --namespace or -ns | | | --key or -K | | | --value or -v | | | --plural-category or -pc | | | --description or -d | | | --ai-instructions or -ai | | | --reset-confirmed | | | --retain-confirmed | |

Notes

--api-key Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

--pat A personal access token that you have generated in your i18nexus account (Can also be set using environment variable I18NEXUS_PERSONAL_ACCESS_TOKEN)

--namespace The new namespace of the string

--key The new key of the string

--value The new value of the string

--plural-category For plural sets, the base-language plural category to update with --value. Use this on the plural root key, for example i18nexus u common:cart.items -v '{{count}} item' --plural-category one.

When --plural-category is used, only the plural value can be updated. To update the base key, namespace, description, or AI instructions, run a separate update without --plural-category.

--description The new description of the string. When Use description as AI context is on, this is also sent to AI during translation.

--ai-instructions String-level AI translation context. Only use this when Use description as AI context is off.

If you are updating the value of a string that contains translations that have been marked confirmed in i18nexus, you will be required to include one of the following options to your command:

--reset-confirmed Confirmed translations of this string will be reset with machine translations of the new value

--retain-confirmed Confirmed translations of this string will be retained

Deleting strings

i18nexus delete-string <namespace:key> or i18nexus d <namespace:key>

i18nexus d common:welcome_msg -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>

The required argument is the namespace and the key of the string you wish to delete, joined with a colon (":"). If your project does not use namespaces or only has one namespace, only the key is necessary.

Options

| Option | Required? | | ------------------- | --------- | | --api-key or -k | ✔ | | --pat or -t | ✔ |

Notes

--api-key Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

--pat A personal access token that you have generated in your i18nexus account (Can also be set using environment variable I18NEXUS_PERSONAL_ACCESS_TOKEN)

Importing strings into your i18nexus project

i18nexus import <filePath>

i18nexus import ./en.json -ns common -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>

The above snippet will read the contents of ./en.json and import them into the base language of your i18nexus project.

This is the equivalent of using the Import tool in the i18nexus web application. However, this CLI command only allows for uploading a JSON file for your base language.

Options

| Option | Required? | | ---------------------- | ------------- | | --api-key or -k | ✔ | | --pat or -t | ✔ | | --namespace or -ns | Conditionally | | --overwrite | |

Notes

--api-key Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

--pat A personal access token that you have generated in your i18nexus account (Can also be set using environment variable I18NEXUS_PERSONAL_ACCESS_TOKEN)

--namespace The namespace in which your strings will be imported. Omit this if your project does not use namespaces. Only required if your project uses namespaces and has more than one namespace.

--overwrite If any keys already exist in the target namespace, overwrite the values with the imported values.

Adding multiple strings

i18nexus bulk-add-strings <filePath> or i18nexus ba <filePath>

i18nexus ba ./base-strings.json -ns common -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>

The above snippet will create multiple new strings in your i18nexus project from a local JSON file. You can add up to 500 strings per bulk-add-strings request.

Use this command when you want to create strings with description and, for projects with separate fields, ai_instructions. If you only need to import plain key/value JSON, use i18nexus import instead.

Just like add-string, translations for new strings will be automatically generated and machine translated for your project's languages.

The JSON file must contain a top-level array of up to 500 objects. Each object should include key and value, and can optionally include description.

When Use description as AI context is on, use description and omit ai_instructions.

When Use description as AI context is off, description is not sent to AI and ai_instructions is sent to AI.

[
  {
    "key": "welcome_title",
    "value": "Welcome to my app",
    "description": "Homepage hero title"
  },
  {
    "key": "welcome_cta",
    "value": "Get started",
    "description": "Use action-oriented onboarding language"
  }
]

If a key already exists in the target namespace, it will be skipped and reported back by the CLI.

Options

| Option | Required? | | ---------------------- | ------------- | | --api-key or -k | ✔ | | --pat or -t | ✔ | | --namespace or -ns | Conditionally |

Notes

--api-key Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

--pat A personal access token that you have generated in your i18nexus account (Can also be set using environment variable I18NEXUS_PERSONAL_ACCESS_TOKEN)

--namespace The namespace in which to create the strings. Omit this if your project does not use namespaces. Only required if your project uses namespaces and has more than one namespace.

Adding new namespaces

i18nexus add-namespace <namespaceTitle>

i18nexus add-namespace common -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN>

The above snippet will create a new namespace in your i18nexus project with the title common.

Options

| Option | Required? | | ------------------- | --------- | | --api-key or -k | ✔ | | --pat or -t | ✔ |

Notes

--api-key Your project API key (Can also be set using environment variable I18NEXUS_API_KEY)

--pat A personal access token that you have generated in your i18nexus account (Can also be set using environment variable I18NEXUS_PERSONAL_ACCESS_TOKEN)