# gt: General Translation CLI tool: Translate
URL: https://generaltranslation.com/en-US/docs/cli/translate.mdx
---
title: Translate
description: How to translate your project
---
## Usage
```bash
npx gt translate
```
**Important:** Run this in your CI pipeline **before** you build your app for production.
## Overview
The `gt translate` command translates your project by 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.
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, make sure you are on the branch that will be used for production.
Set your production API key (`GT_API_KEY`) and project ID (`GT_PROJECT_ID`) as environment variables.
**Note:** A production API key is required. Get one for free at [generaltranslation.com](https://generaltranslation.com/dashboard), or run the [setup wizard](/docs/cli/init) to generate one.
### Translate your project [#translate]
```bash
npx gt translate
```
The `translate` command reads your `gt.config.json` to determine which files to translate, searches your project's source code for translatable content, and generates the necessary translation files.
Translations are automatically saved to your codebase.
See the [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 */}
**Auto-detection:** 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.
### Validate without translating [#validate]
```bash
npx gt 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 to validate your project's `` components and dictionary file without generating translations.
---
## Flags
| Parameter | Description | Type | Default |
| --- | --- | --- | --- |
| `--api-key` | Specify a production API key | `string` | |
| `--project-id` | Specify the project ID | `string` | |
| `--version-id` | Specify a version ID (by default, a hash of the content) | `string` | |
| `--config ` | Specify a path to the GT config file | `string` | `"gt.config.json"` |
| `--tsconfig, --jsconfig ` | Specify a path to the TS or JS config file | `string` | |
| `--src ` | Space-separated glob patterns for source files (relative to root) | `[string]` | `['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` | |
| `--inline` | Include inline `` tags in addition to the dictionary | `boolean` | `true` |
| `--timeout` | Timeout for the translation request in seconds | `number` | `600` |
| `--new, --locales ` | Locales to translate into (appended to `gt.config.json` locales) | `[string]` | |
| `--default-locale ` | The source locale for the project | `string` | `en` |
| `--ignore-errors` | Ignore errors and force translation for valid content | `flag` | `false` |
| `--dry-run` | Validate without translating | `flag` | `false` |
| `--force` | Force retranslation of all content | `flag` | `false` |
| `--force-download` | Force download of all translations | `flag` | `false` |
| `--save-local` | Detect and save local edits before enqueuing translations | `flag` | `false` |
| `--enable-branching` | Enable branching for the project | `flag` | `false` |
| `--branch ` | Specify a custom branch name for translations | `string` | |
| `--disable-branch-detection` | Disable automatic branch detection | `flag` | `false` |
| `--tag [value]` | Tag this translation run (auto-resolves from git if no value provided) | `string` | |
| `-m, --message ` | Message to attach to the translation tag | `string` | |
**Security:** Do not add your API key to the `gt.config.json` file! Set it as an environment variable instead. The CLI automatically reads `GT_API_KEY` if set.
### Key flags
| Flag | Description |
| --- | --- |
| `--dry-run` | Parse and validate your project without communicating with the GT API. Useful for validating your codebase. |
| `--force` | Retranslate all content, overwriting existing translations. Any local changes will be lost. You will be charged for new translations. |
| `--force-download` | Re-download all translations, overwriting local changes. Does not retranslate. |
| `--save-local` | Detect and save local edits to translation files before enqueuing. See [`save-local`](/docs/cli/save-local). |
| `--enable-branching` | Track translations separately for different git branches. See [branching](/docs/cli/branching). |
| `--tag` | Tag a translation run with a human-readable identifier for version tracking. See [tagging](#tagging). |
| `-m, --message` | Attach a descriptive message to a translation tag. See [tagging](#tagging). |
### Configuration file
When running the CLI for the first time, it will attempt to create a `gt.config.json` file in the root of your project. Read more about configuration [here](/docs/cli/reference/config).
## Important tips
### Content sources
The `translate` command recursively searches for translatable content in your project.
By default, it searches in the following directories:
- `./src`
- `./app`
- `./pages`
- `./components`
You can specify alternate directories with the `--src` flag or by modifying the `src` property in your [`gt.config.json`](/docs/cli/reference/config).
### Overwriting translations
By default, the CLI will not overwrite local translation changes unless the source content has changed.
To retranslate content that has already been translated, use `--force`.
**Caution:** `--force` will **overwrite all existing translations and generate new ones**. Any local changes will be lost. You will be charged for new translations.
To re-download translations without retranslating, use `--force-download`.
**Caution:** `--force-download` will overwrite local translation changes and fetch the most recent translations. It will not retranslate any content.
### Tagging [#tagging]
Use the `--tag` and `-m` flags to label translation runs with human-readable identifiers, making it easier to track and identify versions in the dashboard.
#### Tag with a custom identifier
```bash
npx gt translate --tag v2.1.0
```
#### Tag with a custom identifier and message
```bash
npx gt translate --tag v2.1.0 -m "Added checkout page translations"
```
#### Auto-tag from git
Pass `--tag` without a value to automatically use the current git commit hash as the tag id and the commit message as the tag message:
```bash
npx gt translate --tag
```
You can override the commit message with a custom one:
```bash
npx gt translate --tag -m "Release 2.1 translations"
```
#### Message-only tagging
If you pass `-m` without `--tag`, a tag is auto-generated from the current git commit hash (or a random identifier if not in a git repo):
```bash
npx gt translate -m "Weekly translation update"
```
Tagging is non-blocking — if tag creation fails, the translation run continues normally.
### Dictionary file
The `translate` command automatically detects the dictionary file in your project.
By default, it looks for a file named `dictionary.[json|ts|js]` in:
- `./src`
- `./`
You can specify an alternate dictionary file with the `--dictionary` flag or by modifying the `dictionary` property in your [`gt.config.json`](/docs/cli/reference/config).