Configuring a Project with the General Translation CLI
AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.
Configuring a Project with the General Translation CLI
The General Translation CLI (gt, package gtx-cli) reads a gt.config.json file at the project root to know which locales and files to translate. The configure command generates this file through an interactive wizard, but the wizard requires a real terminal and cannot complete in a non-interactive shell such as a CI pipeline.
What you will build
A gt.config.json written by hand for a project made of standalone MDX files, verified with a dry run against the live API before any real translation call is made.
docs/
en/
getting-started.mdx
configuration.mdx
gt.config.json
AI Prompt
Set up a General Translation project for a set of MDX files that live under docs/en/. Requirements: - The GT CLI (gtx-cli) is installed as a dev dependency (`npm install gtx-cli --save-dev`). - `gt configure` is an interactive wizard and exits without writing a file when stdin isn't a real terminal (as in CI or a scripted run). Write gt.config.json by hand instead. - In the "mdx" file type's "include" glob, the source locale directory must be written as the literal placeholder "[locale]" (e.g. "docs/[locale]/**/*.mdx"), not the literal locale code, so the CLI can find source files. - Set the "transform" field to a bare filename pattern containing "[locale]" (e.g. "*.[locale].mdx"). Do not repeat the include pattern's directory prefix in transform, since that produces a nested, duplicated output path. - Verify the config with `gt translate --dry-run` before running a real translation. - Run the verification step below before finishing.
Prerequisites
gtx-cliinstalled as a dev dependency:npm install gtx-cli --save-dev- A General Translation project API key and project ID, available as
GT_API_KEY/GT_PROJECT_IDenvironment variables or passed via--api-key/--project-id - A
package.jsonat the project root (the CLI warns and behaves inconsistently without one)
Note: Output below is trimmed to the fields relevant to each step.
GT_API_KEY/GT_PROJECT_IDare read from the environment automatically if the flags are omitted.
1. The wizard does not work non-interactively
echo "" | npx gtx-cli configure
Real output:
┌ Configuring project... │ ● Welcome! This tool will help you configure your gt.config.json file... ◆ What is the default locale for your project? │ en └
The process exits without writing gt.config.json because the piped, empty stdin never supplies an answer. Any non-interactive environment (CI, a scripted setup, a sandboxed agent) needs to skip this wizard and write the file directly.
2. Write gt.config.json by hand
cat > gt.config.json <<'EOF'
{
"$schema": "https://assets.gtx.dev/config-schema.json",
"defaultLocale": "en",
"locales": ["fr", "es"],
"files": {
"mdx": {
"include": ["docs/[locale]/**/*.mdx"],
"transform": "*.[locale].mdx"
}
}
}
EOF
3. Verify with a dry run before the first real translation attempt
npx gtx-cli translate --config gt.config.json --dry-run
Real output:
┌ Starting translation... │ ~ Project ID: prj_vk7ywgp89cc0qbzgxmx002fd │ ◆ Dry run: No files were sent to General Translation. │ │ Files found in project: │ - docs/en/configuration.mdx │ - docs/en/getting-started.mdx │ └ Done!
Verify the result
Confirm the config resolves the same two files with no warnings:
npx gtx-cli translate --config gt.config.json --dry-run
Expected: the dry run lists every source .mdx file under docs/en/ and prints no path-pattern warning.
How it works
The CLI resolves [locale] in include against the configured defaultLocale to find source files, and resolves it again per target locale to place output. include's directory structure (everything before [locale]) is already carried into the output path, so transform only needs to describe the filename itself. Putting a directory prefix in transform that duplicates part of include nests the output under an extra copy of that path instead of overwriting it.
Common issues
Include pattern missing the [locale] placeholder
Using a literal path such as docs/**/*.mdx (no [locale] token) runs without error but prints: Pattern "docs/**/*.mdx" does not include [locale], so the CLI tool may incorrectly save translated files. The dry run still lists the source files, so the warning is easy to miss; check for it explicitly rather than assuming a clean dry run means the config is correct.
transform repeating the include path
A transform value of docs/[locale]/*.mdx combined with an include of docs/[locale]/**/*.mdx writes output to docs/fr/docs/fr/getting-started.mdx instead of docs/fr/getting-started.mdx. Use a bare filename pattern (*.[locale].mdx) and let include's directory structure carry over on its own.
Running configure or init in a non-interactive shell
Both commands are wizards that need a real terminal. In CI or a sandboxed agent, they either hang waiting on input or, with stdin closed or piped empty, exit without writing anything. Write gt.config.json directly instead of invoking either command.
Next steps
- Translating a project end-to-end with
translate - Saving local edits without triggering a translation with
save-local
verification: status: verified tested_at: "2026-09-29" product_version: "gtx-cli 2.22.4" command: "npx gtx-cli translate --config gt.config.json --dry-run" expected_result: "the dry run lists every source .mdx file under docs/en/ and prints no path-pattern warning"