gptrans

name	gptrans
description	Instructions for using the GPTrans Node.js library for AI-powered translations with smart batching, caching, context-aware translations, refinement, and image translation. Use when adding i18n/localization to a Node.js project, translating text or images between languages, or managing multilingual content.
version	1.0.0
tags	["nodejs","translation","i18n","localization","ai","gpt","multilingual"]

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';

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.

References

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