Configuration

Tstlai Options#

The Tstlai constructor accepts a configuration object matching the TranslationConfig interface.

interface TranslationConfig {
  targetLang: string;
  provider: AIProviderConfig;
  cache?: CacheConfig;
  excludedTerms?: string[];
  translationContext?: string;
}

targetLang

Type: string Required: Yes The ISO language code to translate to (e.g., es, fr_FR). Used for:

• Selecting the translation context.
• Setting the lang attribute on HTML.
• Determining Text Direction (RTL/LTR).

translationContext

Type: string Required: No A description of the content's context to guide the AI's tone and vocabulary choice.

Example: "Marketing website for a B2B SaaS product, professional but approachable tone."

excludedTerms

Type: string[] Required: No An array of words or phrases that should not be translated (e.g., brand names, technical terms). These are passed to the AI model as a strict instruction.

Example: ['tstlai', 'Content Refinery', 'Next.js']

Can also be set via the TSTLAI_EXCLUDED_TEXT environment variable (comma-separated).

provider

Type: AIProviderConfig Required: Yes

cache

Type: CacheConfig Required: No (Defaults to Memory)

Environment Variables#

Contextual Translation#

API Usage

The translateText method accepts an optional context parameter for disambiguation:

// Without context - AI guesses meaning
await tstlai.translateText('Save');

// With context - AI knows it's a button action
await tstlai.translateText('Save', 'es_ES', 'button: save file to disk');

// More examples
await tstlai.translateText('Post', undefined, 'verb: publish content');
await tstlai.translateText('Match', 'de_DE', 'noun: sports game');

JSON Format (CLI)

For the CLI generate command, use the $t / $ctx format:

{
  "actions": {
    "save": { "$t": "Save", "$ctx": "button: save file to disk" },
    "post": { "$t": "Post", "$ctx": "verb: publish content" },
    "file": { "$t": "File", "$ctx": "noun: menu item" }
  },
  "labels": {
    "title": "Welcome"
  }
}

• $t - The text to translate
• $ctx - Context hint (used by AI, stripped from output)

Plain strings (like "title": "Welcome") work as before.

Best Practices

1. Be specific - "verb: publish content" beats just "verb"
2. Include UI context - "button", "menu item", "page title", "error message"
3. Mention domain - "sports", "finance", "medical" when relevant
4. Only when needed - Don't add context to unambiguous phrases like "Welcome to our app"

RTL (Right-to-Left) Support#

tstlai automatically detects RTL languages and provides helpers for setting text direction.

Supported RTL Languages

• Arabic (ar)
• Hebrew (he)
• Persian/Farsi (fa)
• Urdu (ur)
• Pashto (ps)
• Sindhi (sd)
• Uyghur (ug)

Instance Methods

isRtl(targetLangOverride?: string): boolean

Check if the target language uses right-to-left text direction.

tstlai.isRtl(); // Check configured targetLang
tstlai.isRtl('ar_SA'); // Check specific language

getDir(targetLangOverride?: string): 'ltr' | 'rtl'

Get the text direction for the target language.

document.documentElement.dir = tstlai.getDir();

ProcessedPage Response

When using process(), the response includes dir and lang:

interface ProcessedPage {
  html: string;
  translatedCount: number;
  cachedCount: number;
  dir: 'ltr' | 'rtl'; // Text direction
  lang: string; // Target language code
}

Example:

const result = await tstlai.process(html);
console.log(result.dir); // 'rtl' for Arabic
console.log(result.lang); // 'ar_SA'

Code Blocks in RTL Pages

Code should always remain left-to-right, even on RTL pages. Add this CSS:

pre,
code {
  direction: ltr;
  text-align: left;
}