@alnliang/tlv NPM

Translation Language Verifier (TLV)

AI-powered tool for verifying and correcting translations in JSON language files using any OpenAI-compatible API.

Installation

npm install @alnliang/tlv

Usage

import { TranslationVerifier } from '@alnliang/tlv';

const verifier = new TranslationVerifier({
  apiKey: 'your-api-key'
});

const englishJson = {
  "greeting": "Hello {{name}}!",
  "settings": {
    "title": "Settings",
    "theme": "Dark Mode"
  }
};

const translatedFiles = {
  'fr.json': {
    "greeting": "Bonjour {{name}}!",
    "settings": {
      "title": "Paramètres",
      "theme": "Mode sombre"
    }
  }
};

const results = await verifier.verifyTranslations(englishJson, translatedFiles);

Automatic Variable Pattern Detection

TLV automatically detects and handles different variable patterns in your JSON translations:

{{variable}} - Double curly braces (Handlebars, Mustache)
{variable} - Single curly braces
${variable} - Dollar braces (Template literals)
%variable% - Percent signs
$variable$ - Dollar signs
[variable] - Square brackets

No configuration needed. The system analyzes your English JSON and automatically detects which pattern you're using.

Variable Pattern Examples

The verifier automatically detects and validates different variable patterns:

// Single curly braces
const singleCurlyEnglish = {
  welcome: "Hello {name}!",
  message: "You have {count} notifications"
};

// Double curly braces (Handlebars/Mustache)  
const doubleCurlyEnglish = {
  welcome: "Hello {{name}}!",
  message: "You have {{count}} notifications"
};

// Dollar braces (Template literals)
const dollarBraceEnglish = {
  welcome: "Hello ${name}!",
  message: "You have ${count} notifications"
};

// All work automatically - no configuration needed
const results = await verifier.verifyTranslations(englishJson, translatedFiles);

The system will: 1. Auto-detect the variable pattern in your English JSON 2. Validate that translations preserve the exact same pattern 3. Suggest corrections for pattern mismatches 4. Report errors when variables are missing or incorrectly formatted

Configuration

interface VerifierOptions {
  apiKey: string;
  baseURL?: string;      // Default: Google Gemini endpoint
  model?: string;        // Default: gemini-2.5-flash-preview-05-20
  systemMessage?: string;
  userContext?: string;
  ragProvider?: RAGProvider;
  ragOptions?: RAGEnhancedVerificationOptions;
}

Supported Providers

Provider	Base URL
Google Gemini	`https://generativelanguage.googleapis.com/v1beta/openai`
Anthropic Claude	`https://api.anthropic.com/v1`
Groq	`https://api.groq.com/openai/v1`

Any LLM with an OpenAI API compatible endpoint will work.

Other Providers

// OpenAI GPT (baseURL optional - defaults to OpenAI)
const verifier = new TranslationVerifier({
  apiKey: 'your-openai-api-key',
  model: 'gpt-4'
});

// Other providers require baseURL
const verifier = new TranslationVerifier({
  apiKey: 'your-groq-api-key',
  baseURL: 'https://api.groq.com/openai/v1',
  model: 'llama-3.1-70b-versatile'
});

// Local model
const verifier = new TranslationVerifier({
  apiKey: 'not-needed',
  baseURL: 'http://localhost:{PORT}/v1',
  model: 'llama3.1'
});

Response Format

interface VerificationResult {
  [languageKey: string]: {
    errors: Array<{
      stringID: string;
      languageFile: string;
      error: string;
      current: string | null;
      suggestion: string;
    }>;
    "fixed-json": Record<string, any>;
  }
}

Error Handling

try {
  const results = await verifier.verifyTranslations(englishJson, translatedFiles);
} catch (error) {
  console.error('Verification failed:', error.message);
}