Registry / ai-ml / gt
library0.3.15jsnpmunverified

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.

npm install gt
INSTALL
IMPORT
SIG · GT
G
gt
ai-mljavascriptv0.3.15
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 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.
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.
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`.
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.
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.
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.
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.
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.
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.
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.
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.
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`.
Upgrade
Version history
0.3.15latest on npm
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.
Agent activity
21 hits · last 30 days
node
20
OpenAI (training)
1
Resources