{"id":17011,"library":"gt","title":"GT CLI Tool","description":"GT (General Translation) is an AI-powered command-line interface (CLI) tool designed for streamlining internationalization (i18n) and localization (l10n) workflows in JavaScript and TypeScript projects. Currently at version 2.14.17, the project exhibits an active development cadence, frequently releasing patch updates across its core `gt` package and related ecosystem tools like `gt-node`, `@generaltranslation/react-core-linter`, and `gt-tanstack-start`. Its primary differentiator lies in leveraging artificial intelligence for translation processes, aiming to automate and enhance the accuracy of localization efforts. The tool handles various aspects of i18n, from extracting translatable strings to managing and applying translations, supporting integration with different frontend frameworks and build systems, providing a robust, developer-centric approach to managing multilingual applications.","status":"active","version":"2.14.17","language":"javascript","source_language":"en","source_url":"https://github.com/generaltranslation/gt","tags":["javascript","i18n","l10n","translation","internationalization","localization","cli","typescript"],"install":[{"cmd":"npm install gt","lang":"bash","label":"npm"},{"cmd":"yarn add gt","lang":"bash","label":"yarn"},{"cmd":"pnpm add gt","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core translation engine and API communication.","package":"generaltranslation","optional":false},{"reason":"Used for extracting translatable strings from Python-based projects or files within a monorepo context.","package":"@generaltranslation/python-extractor","optional":true}],"imports":[{"note":"The `main` function serves as the programmatic entry point for running GT commands, mirroring CLI operations. Avoid default imports.","wrong":"import gt from 'gt';","symbol":"main","correct":"import { main } from 'gt';"},{"note":"The `cli` function is another programmatic entry point, often used internally or for more direct control over the CLI execution. Preferred ESM imports for type safety.","wrong":"const cli = require('gt').cli;","symbol":"cli","correct":"import { cli } from 'gt';"},{"note":"Import `GTConfig` as a type only for type declarations, not for runtime values. This type represents the structure of the GT configuration file.","wrong":"import { GTConfig } from 'gt';","symbol":"GTConfig","correct":"import type { GTConfig } from 'gt';"}],"quickstart":{"code":"import { main } from 'gt';\nimport * as path from 'path';\nimport * as fs from 'fs';\n\nasync function demonstrateGTWorkflow() {\n  const apiKey = process.env.GT_API_KEY ?? '';\n  if (!apiKey) {\n    console.warn('GT_API_KEY environment variable is not set. Please set it for full functionality.');\n    // For demonstration, we might proceed, but real translation will fail without it.\n  }\n\n  // Ensure a temporary project root for isolated demonstration\n  const tempProjectRoot = path.join(__dirname, '.temp-gt-project');\n  fs.mkdirSync(tempProjectRoot, { recursive: true });\n  process.chdir(tempProjectRoot); // Change working directory for CLI commands\n\n  console.log('--- GT Quickstart Demonstration ---');\n\n  try {\n    // 1. Initialize GT configuration (simulating `gt init`)\n    console.log('Initializing GT project...');\n    await main(['init']);\n\n    // 2. Create a dummy source file for extraction\n    const exampleFilePath = path.join(tempProjectRoot, 'src', 'app.ts');\n    fs.mkdirSync(path.dirname(exampleFilePath), { recursive: true });\n    fs.writeFileSync(exampleFilePath, `\n      // Example file with translatable strings\n      const greeting = 'Hello, world!'; // gt-i18n-key: helloWorld\n      const welcomeMsg = 'Welcome to our application.'; // gt-i18n-key: welcomeMessage\n      console.log(greeting, welcomeMsg);\n    `);\n\n    // 3. Extract translatable strings (simulating `gt extract`)\n    console.log('Extracting translatable strings...');\n    await main(['extract']);\n\n    // 4. Translate strings to a target language (e.g., French)\n    // This step requires an API key to function correctly.\n    console.log('Translating strings to French...');\n    await main(['translate', '--source-locale', 'en', '--target-locales', 'fr', ...(apiKey ? ['--api-key', apiKey] : [])]);\n\n    console.log('\\nGT workflow demonstrated successfully in:', tempProjectRoot);\n    console.log('Check the `.gt` and `translations` directories for generated files.');\n\n  } catch (error) {\n    console.error('\\nGT demonstration failed:', error.message || error);\n  } finally {\n    // Cleanup temporary directory\n    process.chdir(__dirname); // Change back to original directory\n    if (fs.existsSync(tempProjectRoot)) {\n      fs.rmSync(tempProjectRoot, { recursive: true, force: true });\n      console.log('Cleaned up temporary project directory:', tempProjectRoot);\n    }\n  }\n}\n\ndemonstrateGTWorkflow();","lang":"typescript","description":"Demonstrates the typical GT workflow programmatically: initializing a project, extracting translatable strings from source files, and then performing an AI-powered translation to a target language."},"warnings":[{"fix":"Set `process.env.GT_API_KEY = 'YOUR_API_KEY';` before executing GT commands, or pass `--api-key YOUR_API_KEY` directly to the `main` or `cli` functions.","message":"GT relies on an API key for its AI-powered translation services. Running `gt translate` or related commands without a valid key will result in errors or failed operations. Ensure `GT_API_KEY` is set in your environment or passed via command-line flags.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use a tool like `npm outdated` or `yarn why` to check for version discrepancies. Align major and minor versions where possible, or refer to the official documentation for compatibility matrix.","message":"The `gt` package is part of a larger ecosystem (e.g., `gt-react`, `gt-node`, `gtx-cli`). Ensure consistent versioning across related General Translation packages within your project to avoid compatibility issues, especially when consuming libraries that depend on `gt`.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Review your source code to ensure `gt-i18n-key` comments are correctly placed next to translatable strings. Consult the GT documentation for the latest extraction patterns.","message":"GT's string extraction capabilities depend on specific comment directives (e.g., `gt-i18n-key`). If these directives are missing or incorrectly formatted, strings may not be detected for translation, leading to incomplete localization files.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Consult the official migration guide for `gt` to understand changes in configuration schema (`.gt/config.json`) and command-line arguments. Back up your configuration files before upgrading.","message":"While recent updates are patch-level, earlier major versions (e.g., transition from `v1` to `v2`) introduced significant changes to configuration file formats and API interfaces. Always review release notes when upgrading across major versions.","severity":"breaking","affected_versions":"<2.0.0 (upgrade to 2.x)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Set the `GT_API_KEY` environment variable or pass `api-key` flag/argument with a valid key. Register for one on the General Translation website.","cause":"Attempting to run a translation command without a configured or valid General Translation API key.","error":"Error: API key is missing or invalid. Please provide a valid key."},{"fix":"Verify that your source files contain strings marked with `gt-i18n-key` comments or follow other configured extraction patterns. Ensure the `--project-root` and `--source-locale` settings are correct.","cause":"The `gt extract` command failed to identify any strings marked for translation in the configured source files.","error":"Error: No translatable strings found in the project."},{"fix":"Add the `--source-locale <locale_code>` argument to your `translate` command, e.g., `--source-locale en`.","cause":"The `gt translate` command was executed without specifying the source locale for the strings to be translated.","error":"Error: Command 'translate' requires a source locale."}],"ecosystem":"npm","meta_description":null}