@alnliang/tlv/README.md

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

# Translation Language Verifier (TLV)

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

## Installation

```bash
npm install @alnliang/tlv
```

## Usage

```typescript
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:

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

```typescript
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

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

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

## Error Handling

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

## Features

- Automatic variable pattern detection - Works with any variable format
- Translation accuracy verification
- Placeholder validation
- Nested JSON structure support
- Missing key detection
- Automatic correction suggestions
- RAG interface support

## Requirements

- Node.js 16.0.0+
- API key for chosen LLM provider

## License

MIT