i18nexus-cli

# i18nexus-cli **A command line interface for accessing and managing translations through the i18nexus API** ## New to i18nexus? [i18nexus](https://i18nexus.com) is a translation management web application designed for use with i18next, next-intl, and react-intl. Learn more with these quick tutorials: - [next-intl for Next.js App Router Walkthrough](https://i18nexus.com/tutorials/nextjs/next-intl) - [react-i18next for Next.js App Router Walkthrough](https://i18nexus.com/tutorials/nextjs/react-i18next) - [next-i18next for Next.js Pages Router Walkthrough](https://i18nexus.com/tutorials/nextjs/next-i18next) - [react-i18next Walkthrough](https://i18nexus.com/tutorials/react/react-i18next) - [react-intl Walkthrough](https://i18nexus.com/tutorials/react/react-intl) ## Who is this CLI meant for? - Developers who prefer to download and bundle their translation files with their app (especially useful for those who use SSR/SSG frameworks such as Next.js). - Developers who wish to add, edit, or delete strings in their i18nexus project from the command line. ## Installation ```sh 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`. ## Downloading your translations ```sh i18nexus pull -k <PROJECT_API_KEY> ``` The above snippet will download all of your latest translations to your current directory. Your translation files will be downloaded in a file structure based on the convention of your i18n library. ### 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 **`i18next`** and the CLI detects you're using **Next.js + App Router**: ``` . └── 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`**: ``` . └── messages └── locales ├── 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) ## 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` ```sh 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 in your `common` namespace. 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. ### Options | Option | Required? | | ---------------------------- | ------------- | | `--api-key` or `-k` | ✔ | | `--pat` or `-t` | ✔ | | `--key` or `-K` | ✔ | | `--value` or `-v` | ✔ | | `--namespace` or `-ns` | Conditionally | | `--notes` or `-n` | | | `--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. 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 `--notes` Team notes about the string to create (optional) `--ai-instructions` Instructions or context for AI machine translator (optional) ## Updating existing strings `i18nexus update-string <namespace:key>` or `i18nexus u <namespace:key>` ```sh i18nexus u common:welcome_msg -v 'Welcome' -k <PROJECT_API_KEY> -t <YOUR_PERSONAL_ACCESS_TOKEN> ``` The above snippet will update a 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, details, 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` | | | `--details` 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 `--notes` The new team notes of the string `--ai-instructions` Instructions or context for AI machine translator #### 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>` ```sh 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>` ```sh 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. (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 new namespaces `i18nexus add-namespace <namespaceTitle>` ```sh 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`) ## Listening for live translation updates `i18nexus listen` ```sh 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. Many developers prefer to run this automatically alongside their development server. For example, in a Next.js project, you can do the following in your `package.json` using [concurrently](https://www.npmjs.com/package/concurrently): ```json "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)