GPTrans Library Skill

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

First call to t(): Returns the original text immediately. The translation is queued in the background.
Batching: Queued translations are grouped by character count (batchThreshold) and debounce timer (debounceTimeout) to optimize API usage and provide better context to the LLM.
Caching: Completed translations are stored in db/gptrans_<locale>.json. Subsequent calls return instantly from cache.
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';

const gptrans = new GPTrans({
  from: 'en-US',
  target: 'es-AR',
  model: 'sonnet45'
});

// 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

| Option | Type | Default | Description | | --- | --- | --- | --- | | from | string | 'en-US' | Source language (BCP 47) | | target | string | 'es' | Target language (BCP 47) | | model | string \| string[] | 'sonnet45' | Model key or array for fallback chain | | batchThreshold | number | 1500 | Max characters before triggering batch | | debounceTimeout | number | 500 | Milliseconds to wait before processing | | freeze | boolean | false | Prevent new translations from being queued | | name | string | '' | Instance name (isolates cache files) | | context | string | '' | Default context for translations | | instruction | string | '' | Additional instruction for the translator (tone, style). Does not affect cache key | | promptFile | string | null | Custom prompt file path (overrides built-in) | | debug | boolean | false | Enable debug output |

Common Tasks

Translate text with parameter substitution

const gptrans = new GPTrans({ 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({
  from: 'en',
  target: 'fr',
  model: ['sonnet45', 'gpt41']  // falls back to gpt41 if sonnet45 fails
});

Pre-translate all pending texts

const gptrans = new GPTrans({ 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({ 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({ 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({ 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({
  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({ 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({ 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({ 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({
  from: 'es-ES',
  target: 'es-AR',
  model: 'sonnet45'
});

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: ['sonnet45', 'gpt41']) for production resilience with automatic fallback.
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

| Method | Returns | Description | | --- | --- | --- | | new GPTrans(options) | GPTrans | Create instance with from, target, model, etc. | | .t(text, params?) | string | Translate text (sync). Returns cached or original. | | .get(key, text) | string \| undefined | Get translation by key, queue if missing. | | .setContext(context?) | this | Set context for next batch (gender, tone, etc.). | | .setFreeze(freeze?) | this | Enable/disable freeze mode at runtime. | | await .preload(options?) | this | Pre-translate all pending texts. Options: { references, baseLanguage }. | | await .refine(instruction, options?) | this | Refine existing translations. Accepts string or array. | | await .img(path, options?) | string | Translate image text. Returns output path. | | await .purge() | this | Remove orphaned translations from cache. | | GPTrans.isLanguageAvailable(code) | boolean | Check if a language code is supported. |