Gptrans

GPTrans Library Skill

Table of Contents

• Overview
• Installation
• Core Concepts
• Basic Usage
• Common Tasks
• Agent Usage Rules
• API Quick Reference
• References

Overview

GPTrans is a Node.js library that provides AI-powered translations with smart batching, caching, and context awareness. It uses LLMs (via ModelMix) to produce high-quality, culturally-adapted translations while minimizing API calls through intelligent debouncing and batch processing.

Use this skill when:

• Adding internationalization (i18n) or localization to a Node.js application
• Translating text content between languages using AI
• Translating images between languages (via Gemini)
• Managing multilingual content with caching and manual correction support
• Building tools that need context-aware translations (gender, tone, domain)
• Pre-translating or bulk-translating content with preload()
• Refining existing translations with specific style instructions

Do NOT use this skill for:

• Python or non-Node.js projects
• Simple key-value i18n (use i18next or similar instead)
• Projects that don't need AI-quality translations

Installation

npm install gptrans

Environment Setup

GPTrans requires API keys for the underlying LLM providers. Create a .env file:

OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
GEMINI_API_KEY=your_gemini_api_key  # only for image translation

Dependencies

GPTrans uses ModelMix internally for LLM calls. It is installed automatically as a dependency.

Core Concepts

How It Works

1. First call to t(): Returns the original text immediately. The translation is queued in the background.
2. Batching: Queued translations are grouped by character count (batchThreshold) and debounce timer (debounceTimeout) to optimize API usage and provide better context to the LLM.
3. Caching: Completed translations are stored in db/gptrans_<locale>.json. Subsequent calls return instantly from cache.
4. Second call to t(): Returns the cached translation.

Language Tags

GPTrans uses BCP 47 language tags: en-US, es-AR, pt-BR, fr, de, etc. Region can be omitted for universal variants (e.g., es for generic Spanish).

Translation Cache Files

Translations are stored as JSON in db/ directory:

• db/gptrans_<target>.json — cached translations for target locale
• db/gptrans_from_<source>.json — source text registry

You can manually edit translation files to override specific entries.

Basic Usage

import GPTrans from 'gptrans';
import path from 'node:path';

const dbPath = path.join(import.meta.dirname, 'db');
const gptrans = new GPTrans({
  path: dbPath,
  from: 'en-US',
  target: 'es-AR'
});

// Translate text — returns original on first call, cached translation after
console.log(gptrans.t('Hello, {name}!', { name: 'John' }));

// Context-aware translation (e.g., gender)
console.log(gptrans.setContext('Message is for a woman').t('You are very good'));

// Context auto-clears — pass empty to reset
console.log(gptrans.setContext().t('Welcome back'));

Constructor Options

Common Tasks

Translate text with parameter substitution

const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });
console.log(gptrans.t('Hello, {name}!', { name: 'Martin' }));
// First call: "Hello, Martin!" (original)
// After caching: "Hola, Martin!" (translated)

Use model fallback for resilience

const gptrans = new GPTrans({
  path: dbPath,
  from: 'en',
  target: 'fr',
  model: ['sonnet5@50', 'gpt56luna@100']
});

Use model@<effort> with an integer from 0 to 100 to override the unified effort for one model. The default chain uses sonnet5 at effort 50, then falls back to gpt56luna at effort 100.

Pre-translate all pending texts

const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es' });

// Register texts
gptrans.t('Welcome');
gptrans.t('Sign in');
gptrans.t('Sign out');

// Wait for all translations to complete
await gptrans.preload();

// Now all calls return cached translations
console.log(gptrans.t('Welcome'));  // "Bienvenido"

Pre-translate with reference languages

Use existing translations in other languages as context for better accuracy:

const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'fr' });
await gptrans.preload({
  references: ['en', 'pt']  // AI sees English and Portuguese as reference
});

Pre-translate using an alternate base language

Translate from an intermediate language instead of the original (useful for gender-neutral intermediaries):

const gptrans = new GPTrans({ path: dbPath, from: 'es', target: 'pt' });
await gptrans.preload({
  baseLanguage: 'en',       // translate FROM English instead of Spanish
  references: ['es']        // show original Spanish for context
});

Set context for gender-aware translations

const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });

// Context applies to next translation(s) in the batch
console.log(gptrans.setContext('The user is female').t('You are welcome'));

// Reset context
console.log(gptrans.setContext().t('Thank you'));

Set instruction for translation style

const gptrans = new GPTrans({
  path: dbPath,
  from: 'en', target: 'es-AR',
  instruction: 'Use a formal and professional tone'
});

console.log(gptrans.t('Welcome to our platform'));

Refine existing translations

Improve cached translations with specific instructions:

const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es-AR' });

// Single instruction
await gptrans.refine('Use a more colloquial tone');

// Multiple instructions (single API pass — preferred)
await gptrans.refine([
  'Use "vos" instead of "tu"',
  'Shorten texts where possible without losing meaning',
  'Use a more friendly and natural tone'
]);

// Custom refine prompt
await gptrans.refine('More formal', { promptFile: './my-refine-prompt.md' });

Translate an image

Requires GEMINI_API_KEY. Auto-detects language folders for output path:

const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es' });

// en/banner.jpg → es/banner.jpg (auto sibling folder)
const translatedPath = await gptrans.img('en/banner.jpg');

// With options
const result = await gptrans.img('en/hero.jpg', {
  quality: '1K',
  jpegQuality: 92,
  prompt: 'Translate all visible text to Spanish. Keep layout and style.'
});

Freeze mode (prevent new translations)

const gptrans = new GPTrans({ path: dbPath, from: 'en', target: 'es', freeze: true });

// Returns original text, logs "[key] text" — nothing queued
console.log(gptrans.t('New text'));

// Toggle at runtime
gptrans.setFreeze(false);

Purge orphaned translations

Remove cached translations whose source text no longer exists:

await gptrans.purge();

Translate between regional variants

// Spain Spanish → Argentina Spanish
const es2ar = new GPTrans({
  path: dbPath,
  from: 'es-ES',
  target: 'es-AR'
});

console.log(es2ar.t('Eres muy bueno'));

Check language availability

import GPTrans from 'gptrans';

if (GPTrans.isLanguageAvailable('pt-BR')) {
  // Language is supported
}

Agent Usage Rules

• Always check package.json for gptrans before running npm install.
• Store API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY) in .env. Never hardcode keys.
• Use BCP 47 language tags for from and target (e.g., en-US, es-AR, pt-BR, or just es).
• The t() method is synchronous and non-blocking. It returns the original text on first call and the cached translation on subsequent calls. Do NOT await it.
• To ensure translations are complete before using them, call await gptrans.preload() after registering texts with t().
• Use setContext() for gender-aware or domain-specific translations. Context is captured per-batch and auto-resets when changed.
• Use the instruction constructor option for style/tone guidance (e.g., "Use a more natural tone"). Unlike context, instruction does NOT affect the cache key — different instructions for the same text overwrite the same translation entry.
• Prefer passing an array of instructions to refine() over multiple calls — it processes everything in a single API pass.
• Use model arrays (model: ['sonnet5@50', 'gpt56luna@100']) for production resilience with automatic fallback. The optional @<effort> suffix accepts integers from 0 to 100 and applies only to that model.
• Translation caches live in db/gptrans_<locale>.json. These files can be manually edited to override specific translations.
• The name constructor option isolates cache files (db/gptrans_<name>_<locale>.json), useful for multiple independent translation contexts in the same project.
• When translating images, ensure GEMINI_API_KEY is set. The img() method auto-creates sibling language folders.
• Do NOT use freeze: true during initial translation — it prevents all new translations from being queued.
• Variables in curly braces ({name}, {count}) in source text are preserved through translation. Parameter substitution happens at t() call time.

API Quick Reference

References

• GitHub Repository
• npm Package
• ModelMix (underlying LLM library)