GT CLI Tool

Common errors

• Error: API key is missing or invalid. Please provide a valid key.

  cause Attempting to run a translation command without a configured or valid General Translation API key.
  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.

• Error: No translatable strings found in the project.

  cause The `gt extract` command failed to identify any strings marked for translation in the configured source files.
  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.

• Error: Command 'translate' requires a source locale.

  cause The `gt translate` command was executed without specifying the source locale for the strings to be translated.
  fix Add the `--source-locale <locale_code>` argument to your `translate` command, e.g., `--source-locale en`.

Warnings

• gotcha 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.
  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.
• gotcha 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`.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install gt npm
• yarn add gt yarn
• pnpm add gt pnpm

Imports

• main
  wrong:

  import gt from 'gt';

  correct:

  import { main } from 'gt';

  The `main` function serves as the programmatic entry point for running GT commands, mirroring CLI operations. Avoid default imports.
• cli
  wrong:

  const cli = require('gt').cli;

  correct:

  import { cli } from 'gt';

  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.
• GTConfig
  wrong:

  import { GTConfig } from 'gt';

  correct:

  import type { GTConfig } from 'gt';

  Import `GTConfig` as a type only for type declarations, not for runtime values. This type represents the structure of the GT configuration file.

Quickstart

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.

import { main } from 'gt';
import * as path from 'path';
import * as fs from 'fs';

async function demonstrateGTWorkflow() {
  const apiKey = process.env.GT_API_KEY ?? '';
  if (!apiKey) {
    console.warn('GT_API_KEY environment variable is not set. Please set it for full functionality.');
    // For demonstration, we might proceed, but real translation will fail without it.
  }

  // Ensure a temporary project root for isolated demonstration
  const tempProjectRoot = path.join(__dirname, '.temp-gt-project');
  fs.mkdirSync(tempProjectRoot, { recursive: true });
  process.chdir(tempProjectRoot); // Change working directory for CLI commands

  console.log('--- GT Quickstart Demonstration ---');

  try {
    // 1. Initialize GT configuration (simulating `gt init`)
    console.log('Initializing GT project...');
    await main(['init']);

    // 2. Create a dummy source file for extraction
    const exampleFilePath = path.join(tempProjectRoot, 'src', 'app.ts');
    fs.mkdirSync(path.dirname(exampleFilePath), { recursive: true });
    fs.writeFileSync(exampleFilePath, `
      // Example file with translatable strings
      const greeting = 'Hello, world!'; // gt-i18n-key: helloWorld
      const welcomeMsg = 'Welcome to our application.'; // gt-i18n-key: welcomeMessage
      console.log(greeting, welcomeMsg);
    `);

    // 3. Extract translatable strings (simulating `gt extract`)
    console.log('Extracting translatable strings...');
    await main(['extract']);

    // 4. Translate strings to a target language (e.g., French)
    // This step requires an API key to function correctly.
    console.log('Translating strings to French...');
    await main(['translate', '--source-locale', 'en', '--target-locales', 'fr', ...(apiKey ? ['--api-key', apiKey] : [])]);

    console.log('\nGT workflow demonstrated successfully in:', tempProjectRoot);
    console.log('Check the `.gt` and `translations` directories for generated files.');

  } catch (error) {
    console.error('\nGT demonstration failed:', error.message || error);
  } finally {
    // Cleanup temporary directory
    process.chdir(__dirname); // Change back to original directory
    if (fs.existsSync(tempProjectRoot)) {
      fs.rmSync(tempProjectRoot, { recursive: true, force: true });
      console.log('Cleaned up temporary project directory:', tempProjectRoot);
    }
  }
}

demonstrateGTWorkflow();