Usage Guide
Usage guide for the GT command line tool
Overview
This guide will walk you through the process of using General Translation's CLI tool (gtx-cli) to translate your project.
The CLI tool is compatible with any i18n library, whether you are using gt-next, gt-react, or third-party libraries like next-intl or react-i18next.
The CLI tool is responsible for connecting 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:
Use Cases
Translating GT projects
The CLI tool can be used to translate your projects which use gt-next or gt-react.
This guide assumes you have already setup your codebase to use gt-next or gt-react according to the gt-next or gt-react tutorials.
- First, you will need to initialize the CLI tool in your project.
- 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.
- Then, add your API key and Project ID to your environment variables.
- Finally, run the translation command.
By default, the CLI tool will publish the translations to the General Translation CDN, so they are ready to be used in your project.
If you would like to disable this behavior (for example, if you are loading translations from a different source), add the --no-publish flag to the command.
See the API reference for more information on the translate command.
Translating language files (3rd party i18n libraries or standalone GT projects)
The CLI tool allows you to translate language files for 3rd party i18n libraries or with a stand-alone 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 desired languages.
- First, you will need to initialize the CLI tool in your project.
This command will create a gt.config.json file in the root of your project, containing some basic configuration settings, such as your project's default locale and supported locales.
- 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.
- Then, add your API key and Project ID to your environment variables.
- Finally, run the translation command.
By default, the CLI tool will look in the translationsDir directory specified in your gt.config.json file for language files to translate.
It will use the defaultLocale specified in your gt.config.json file as the source language.
It will also publish the translations to the General Translation CDN, so they are ready to be used in your project.
If you would like to disable this behavior, add the --no-publish flag to the command.
Generating language files for GT projects
The CLI tool can be used to generate language files for projects which use gt-next or gt-react.
This use case is useful if you would like to use your own translation provider.
Unlike other i18n libraries, gt-next and gt-react support in-line translations, meaning there is no traditional JSON file structure containing keys and values for each language.
This means that in order to track changes to text, GT libraries store the hashes of the original text in the source code.
This internal data structure (containing hashes) is hard to work with, and therefore the CLI tool provides a handy command to generate language files for your project.
- First, you will need to initialize the CLI tool in your project.
When asked "Where are your language files stored?", select the "Local" option.
- Run:
This command will generate a source file for your default locale, and all other locales you have configured for your project.
The content for each file is the same, and will be merged with any previous translations you have in your project.
See the API reference for more information on the generate command.
Notes
gtx-cli translateis used to automatically generate translations for your project.- If you are using a 3rd party i18n library, you can automatically update all of your translation JSON files every time your project changes. Just add the
gtx-cli translatecommand to your build or CD process before the build command to automatically add translations to your project.
Next steps
- See the CLI API reference for more information.
- If you want to see live translations in development (think hot reload), check out the
<T>component.