Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
main
✓ import { main } from 'gt';
✗ import gt from 'gt';
The `main` function serves as the programmatic entry point for running GT commands, mirroring CLI operations. Avoid default imports.
cli
✓ import { cli } from 'gt';
✗ const cli = require('gt').cli;
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
✓ import type { GTConfig } from 'gt';
✗ import { 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.
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();
gt --version
Debug
Known issues
gotchaGT 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.fixSet `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.
affects: >=2.0.0
gotchaThe `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`.fixUse 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.
affects: >=2.0.0
gotchaGT'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.fixReview 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.
affects: >=2.0.0
breakingWhile 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.fixConsult 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.
affects: <2.0.0 (upgrade to 2.x)
Errors
Common errors & fixes
Error: API key is missing or invalid. Please provide a valid key.
Attempting to run a translation command without a configured or valid General Translation API key.
fixSet 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.
The `gt extract` command failed to identify any strings marked for translation in the configured source files.
fixVerify 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.
The `gt translate` command was executed without specifying the source locale for the strings to be translated.
fixAdd the `--source-locale <locale_code>` argument to your `translate` command, e.g., `--source-locale en`.
Audit
Dependencies
generaltranslationrequiredCore translation engine and API communication.
@generaltranslation/python-extractoroptionalUsed for extracting translatable strings from Python-based projects or files within a monorepo context.