# gtx-cli: General Translation CLI tool: Translate
URL: https://generaltranslation.com/en-US/docs/cli/translate.mdx
---
title: Translate
description: How to translate your project
---
## Usage
Run this in your CI pipeline **before** you build your app for production.
```bash
npx gtx-cli translate
```
**Note:** This command requires a production API key! Get one on the
[platform](https://generaltranslation.com/dashboard).
## Overview
The `gtx-cli translate` command translates your project by first reading your `gt.config.json` file to determine which files to translate.
If you are using [`gt-next`](/docs/next), [`gt-react`](/docs/react), or [`gt-react-native`](/docs/react-native), it will also search your project's source code for inline content (such as `` components and `useGT` hooks) and generate the necessary translation files for you.
Additionally, it includes content from the dictionary file (if one is provided).
This command is the primary way of using the General Translation API and related services.
**For Production Use Only!**
This command is meant 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 (`GT_API_KEY`) and Project ID (`GT_PROJECT_ID`) in your environment variables.
## Usage
There are 2 primary ways to use the `translate` command. The first method requires a production API key.
We recommend running the setup wizard: [`npx gtx-cli
configure`](/docs/cli/configure) to help configure your project before running
the `translate` command. Depending on how your project is configured, the
behavior of the translate command may change.
### Method 1: Translate your project [#translate]
```bash
npx gtx-cli translate
```
The `translate` command will read your `gt.config.json` file to determine which files to translate, as well as search your project's source code for translatable content, before generating the necessary translation files for you.
Translations will be automatically saved to your codebase.
See the [CLI config docs](/docs/cli/reference/config#files) for more details.
{/* These links point to our own SDK docs intentionally — we want to show how our CLI handles these libraries, not link to the external library sites */}
If you are using [`next-intl`](/docs/next), [`react-i18next`](/docs/react), or
[`next-i18next`](/docs/react-native), the CLI tool will automatically detect
your i18n library by reading your `package.json` file, and will translate your
JSONs while respecting your i18n library's syntax.
### Method 2: Validate your project's `` components and dictionary file. [#validate]
```bash
npx gtx-cli translate --dry-run
```
If you are using [`gt-next`](/docs/next), [`gt-react`](/docs/react), or [`gt-react-native`](/docs/react-native), you can use this method to validate your project's `` components and dictionary file.
This ensures that your project is correctly configured and that the translations will be valid and accurate.
No translations will be generated if the `--dry-run` flag is provided.
---
## Flags
| Parameter | Description | Type | Optional | Default |
| ------------------------------- | -------------------------------------------------------------------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--api-key` | Specify a production API key | `string` | `true` | |
| `--project-id` | Specify the project ID | `string` | `true` | |
| `--version-id` | Specify a version ID (by default, a hash of the content) | `string` | `true` | |
| `--config ` | Specify a path to the GT config file | `string` | `true` | `"gt.config.json"` |
| `--tsconfig, --jsconfig ` | Specify a path to the TS or JS config file | `string` | `true` | |
| `--src ` | Space-separated list of glob patterns to match source files. Should be relative to root directory. | `[string]` | `true` | `[ 'src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}', ]` |
| `--dictionary ` | Specify a path to the dictionary file | `string` | `true` | |
| `--inline` | Include inline `` tags in addition to the dictionary | `boolean` | `true` | `true` |
| `--timeout` | The timeout for the translation request in seconds | `number` | `true` | `600` |
| `--new, --locales ` | Locales to translate your project into | `[string]` | `true` | |
| `--default-locale ` | The source locale for the project | `string` | `true` | `en` |
| `--ignore-errors` | Ignore errors and force translation for valid content | `flag` | `true` | `false` |
| `--dry-run` | Dry run the command | `flag` | `true` | `false` |
| `--force` | Force a retranslation of your project | `flag` | `true` | `false` |
| `--force-download` | Force a download of all translations for the project | `flag` | `true` | `false` |
| `--save-local` | Detect and save local edits before enqueuing translations | `flag` | `true` | `false` |
| `--enable-branching` | Enable branching for the project | `flag` | `true` | `false` |
| `--branch ` | Specify a custom branch name to use for translations | `string` | `true` | |
| `--disable-branch-detection` | Disable automatic branch detection and use only the manually specified branch | `flag` | `true` | `false` |
All of these parameters are optional.
Do not add your API key to the `gt.config.json` file! You should set it as an
environment variable instead. The CLI will automatically read `GT_API_KEY` if
it is set.
There are a few key parameters:
| Parameter | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dry-run` | This flag will cause the CLI to parse and validate your project, but will not communicate with the GT API. This is useful for validating your codebase. |
| `--api-key` | Unless you are using `--dry-run`, you must provide a production API key. |
| `--project-id` | Similarly, unless you are using `--dry-run`, you must provide a project ID. |
| `--new, --locales ` | Locales to translate your project into. These will be appended to the locales specified in your `gt.config.json` file. |
| `--force` | This flag will force a retranslation of your project and will overwrite all existing translations. |
| `--force-download` | This flag will force a download of all translations and will overwrite any changes you have made to the translations locally. |
| `--save-local` | Detect and save any local edits to translation files before enqueuing translations. See [`save-local`](/docs/cli/save-local) for more details. |
| `--enable-branching` | Enable branching to track translations separately for different git branches. See [branching](/docs/cli/branching) for more details. |
| `--branch ` | Specify a custom branch name instead of auto-detecting from git. |
| `--disable-branch-detection` | When using `--branch`, disables additional branch relationship detection (incoming/checked-out branches). |
### Configuration file
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.
Read more about the `gt.config.json` file [here](/docs/cli/reference/config).
## Important tips
### Content sources
The `translate` command will recursively search for translatable content in your project.
By default, it searches in the following directories:
- `./src`
- `./app`
- `./pages`
- `./components`
You can specify alternate directories to search by using the `--src` flag,
or by modifying the `src` property in your [`gt.config.json`](/docs/cli/reference/config) file.
### Overwriting translations
By default, the CLI tool will not overwrite any changes you have made to translations locally unless the source content has changed.
If you would like to retranslate project content that has already been translated, you can use the `--force` flag.
Using `--force` will **overwrite all existing translations and generate new
ones**. Any changes you have made to the translations locally will be lost.
You will be charged for all new translations.
If you have already fetched the most recent project translations and would like to download them again, you can use the `--force-download` flag.
Using `--force-download` will overwrite any changes you have made to the
translations locally and will fetch the most recent translations. It will not
retranslate any content.
### Dictionary file
The `translate` command will automatically detect the dictionary file in your project.
By default, it looks for a file named `dictionary.[json|ts|js]` in the following directories:
- `./src`
- `./`
You can specify an alternate dictionary file by using the `--dictionary` flag,
or by modifying the `dictionary` property in your [`gt.config.json`](/docs/cli/reference/config) file.