The CLI Tool
The General Translations CLI tool
Overview
This is a reference doc on the General Translation CLI tool. For a step by step guide, check out the Deploying to Production guide.
Installation
What does the CLI tool do?
The CLI tool is a script that will scan your entire app for content to be translated.
During this scan, it will parse and validate any <T> components or dictionaries that are used in your codebase.
After parsing and validating content, the CLI tool will save the corresponding hashes and content on our servers. If eager translation is specified, the GT API will pre-translate the content in the specified locales and cache it on our CDN.
What is eager translation?
Eager translation is the process of translating content in advance. This way, when the user requests a page, the translated content is already available in the CDN and can be served immediately.
Of course, it is not always the best practice to translate every single language in advance. You should consider the languages that are most commonly used by your audience and translate those. The rest can be translated at runtime as necessary.
Is this required?
Yes, you must run the CLI tool as part of your CI/CD pipeline in order to ensure that your content is able to be translated in production.
Due to the nature of React (and Next.js client components) being rendered on the client side, API Keys and similar credentials cannot be passed to the client. The CLI tool is necessary to prevent abuse from malicious actors.
Running the CLI tool allows GT to pre-authorize your content for translation via hashing, eliminating security vulnerabilities.
Translating
To use the CLI tool, run the following command from the root of your project:
For Production Use Only!
Because this CLI tool publishes translated content to the CDN, it is meant to only be used for production builds and should not be used in development. Before running this command, please make sure you are on the branch that will be used for production. Remember to also specify your production API key and Project ID in your environment variables.
Flags
| Prop | Type | Default |
|---|---|---|
--api-key | string | - |
--project-id | string | - |
--options | string | gt.config.json |
--locales | string | - |
--dictionary | string | - |
--dry-run | boolean | false |
--ignore-errors | boolean | false |
--inline | boolean | true |
When running the CLI tool for the first time, it will attempt to create a gt.config.json file in the root of your project.
This file contains metadata about your project that is used to translate your content.
Setup
Additionally, the CLI tool can automatically scan and setup your project for translation. If you are using General Translation for the first time, we recommend running the setup to get started.
Stash your changes!
This will modify your codebase, so make sure to either stash or commit your changes first.
Running this command will wrap <T> components around the top level of JSX elements which contain translatable content.
It will also wrap any non-static content with <Var> components.
Here are some examples of what the scan will convert:
Will be converted to:
The CLI will only wrap direct children inside JSX elements. It will wrap other JSX elements separately with their own <T> components.
Experimental
This feature is currently experimental and may not work perfectly.
After running the scan, you should manually review the output and make sure it is correct.
In particular, note that any non-static JSX Expressions {...} will be wrapped in <Var> components.
You may need to manually review and edit these cases.
Please report any issues you run into here.
Additionally, the CLI tool will automatically detect the framework you are using. If your project is
a Next.js app, it will automatically wrap <GTProvider> components at the top level layout.tsx of your app, as well as
modify the lang attribute in the <html> tag to dynamically set the language of your app.
Flags
| Prop | Type | Default |
|---|---|---|
--framework | string | - |
--src | string | - |