Overview

This guide will walk you through using General Translation’s CLI tool (gtx-cli) to translate your project.

The CLI tool is compatible with any i18n library, whether you’re using gt-next, gt-react, or third-party libraries like next-intl or react-i18next.

The CLI tool connects your project to General Translation’s AI translation service.

There are several ways to use the CLI tool; please navigate to the relevant section for your use case.

Installation

To install the CLI tool, run the following command:

npm i gtx-cli

yarn add --dev gtx-cli

bun add --dev gtx-cli

pnpm add --save-dev gtx-cli

Use cases

Translating GT projects

The CLI tool can be used to translate your projects that use gt-next or gt-react.

This guide assumes you have already set up your codebase to use gt-next or gt-react according to the gt-next or gt-react tutorials.

1. First, you will need to configure your project's GT settings.

npx gtx-cli configure

2. Next, you will need to create a project in the General Translation dashboard.

After creating a project, you will need to generate a production API key. Navigate to the "API Keys" page and click the "Create API Key" button.

3. Then add your API key and project ID to your environment variables.

GT_API_KEY=<your-api-key>
GT_PROJECT_ID=<your-project-id>

4. Finally, run the translation command.

npx gtx-cli translate

See the API reference for more information on the translate command.

Translating language files (third‑party i18n libraries or standalone GT projects)

The CLI tool allows you to translate language files for third‑party i18n libraries or with a standalone implementation of gt-next or gt-react.

Most i18n libraries rely on JSON files to store translation data. The CLI tool can be used to automatically translate these JSON files into your target languages.

1. First, you will need to configure your project’s GT settings.

npx gtx-cli configure

This command will create a gt.config.json file in the root of your project, containing basic configuration settings, such as your project's default locale and supported locales.

2. Next, you need to create a project in the General Translation dashboard.

After creating a project, generate a production API key. Navigate to the “API Keys” page and click the “Create API Key” button.

3. Then add your API key and project ID to your environment variables.

GT_API_KEY=<your-api-key>
GT_PROJECT_ID=<your-project-id>

4. Finally, run the translation command.

npx gtx-cli translate

Generating language files for GT projects

The CLI tool can be used to generate language files for projects that use gt-next or gt-react.

This is useful if you want to use your own translation provider.

Unlike other i18n libraries, gt-next and gt-react support inline translations, meaning there isn’t a traditional JSON file structure containing keys and values for each language.

To track changes to text, GT libraries store hashes of the original text in the source code.

This internal data structure (containing hashes) is awkward to work with, so the CLI tool provides a handy command to generate language files for your project.

1. First, you’ll need to configure your project’s GT settings.

npx gtx-cli configure

When prompted to save translations on the GT CDN, choose the “No” option.

2. Run:

npx gtx-cli generate

This command will generate a source file for your default locale, and for all other locales you’ve configured for your project.

The content of each file is the same, and will be merged with any previous translations in your project.

See the API reference for more information on the generate command.

Notes

• gtx-cli translate is used to automatically generate translations for your project.
• If you’re using a third‑party i18n library, you can automatically update all your translation JSON files whenever your project changes. Just add the gtx-cli translate command to your build or CD process before the build step to automatically add translations to your project.

Next steps

• See the CLI API reference for more information.