@alaikis/translation-sdk

Laker Translation Service SDK for JavaScript/TypeScript - Simplified Single Entry Point

Installation

npm install @alaikis/translation-sdk

Or use directly in browser via CDN:

<script src="https://unpkg.com/@alaikis/translation-sdk@latest/translation-client.js"></script>

Quick Start

Browser (UMD Global)

<script src="https://unpkg.com/@alaikis/translation-sdk@latest/translation-client.js"></script>
<script>
  // Global is available as window.LakerTranslation
  // baseUrl is optional - defaults to official production endpoint
  const client = new LakerTranslation.TranslationClient({
    token: 'your-jwt-token',
    senseId: 'your-sense-id'
  });

  // Translate text with optional fingerprint
  client.translate('Hello world', 'en', 'zh', 'user-fingerprint-123')
    .then(result => console.log(result));
</script>

ES Module / CommonJS (Node.js/Bundlers)

import { TranslationClient, createTranslation } from '@alaikis/translation-sdk';

// Option 1: Use constructor directly
// baseUrl is optional - defaults to official production endpoint
const client = new TranslationClient({
  token: 'your-jwt-token',
  senseId: 'your-sense-id'
});

// Option 2: Use helper function (recommended)
// baseUrl is optional in the 3rd parameter
const client = createTranslation('your-jwt-token', 'your-sense-id');

// With custom baseUrl
const client = createTranslation('your-jwt-token', 'your-sense-id', {
  baseUrl: 'https://api.your-custom-domain.com'
});

API Reference

TranslationClient Constructor

new TranslationClient(options: TranslationClientOptions)

Options:

{
  baseUrl?: string;           // API base URL, optional, default: https://api.hottol.com/laker/
  token: string;             // JWT authentication token (required)
  senseId: string;           // Translation sense ID (required)
  fingerprint?: string;       // Default client-level fingerprint (optional)
  maxCacheSize?: number;     // Max LRU cache size for LLM translations, default: 10000
  crossTabSync?: {
    enabled: boolean;        // Enable cross-tab synchronization, default: false
    channelName?: string;
    storageKeyPrefix?: string;
  };
}

Methods

translate(text, srcLang?, dstLang?, fingerprint?)

Translate text. First lookup in cache, if not found request from backend and cache result.

async translate(
  text: string,
  srcLang?: string,
  dstLang?: string,
  fingerprint?: string  // Override client-level fingerprint (optional)
): Promise<string>

Lookup Priority:

1. If fingerprint parameter provided → search that fingerprint's cache
2. If client has default fingerprint set (options.fingerprint) → search that
3. Fallback to common translations
4. If not found in any cache → request from backend and cache

lookup(text, fingerprint?)

Lookup translation only from cache, no network request if not found.

lookup(text: string, fingerprint?: string): string | null

Returns the translated string if found, null otherwise.

loadFingerprint(fingerprint)

Preload all cached translations for a specific fingerprint from backend. Called automatically if you call translate() with an unloaded fingerprint.

async loadFingerprint(fingerprint: string): Promise<TranslationItem[]>

getStats()

Get cache statistics.

getStats(): string

extractTemplate(text)

Extract template from text with numeric placeholders (e.g. Page 1 of 10 → Page %1 of %2).

extractTemplate(text: string): ExtractedTemplate

Fingerprint Personalization

The SDK supports per-user personalized translations via fingerprints. Every translation lookup/request can specify a fingerprint.

Example with multiple users:

// Client has no default fingerprint
const client = new TranslationClient({
  baseUrl: 'https://api.example.com',
  token: 'token',
  senseId: 'sense-123'
});

// Translate for user 1
const translation1 = await client.translate(text, 'en', 'zh', 'fingerprint-user-1');

// Translate for user 2
const translation2 = await client.translate(text, 'en', 'zh', 'fingerprint-user-2');

Example with fixed client fingerprint:

// Client has default fingerprint for current user
const client = new TranslationClient({
  baseUrl: 'https://api.example.com',
  token: 'token',
  senseId: 'sense-123',
  fingerprint: 'current-user-fingerprint'
});

// Uses client fingerprint by default
const result = await client.translate(text);

// Override for a specific translation
const specialResult = await client.translate(text, 'en', 'zh', 'another-fingerprint');

Features

• Single Entry Point: All functionality in TranslationClient, no complex layering
• Lazy Loading: Fingerprints are automatically loaded on first use
• LRU Cache: Caches LLM translation results to avoid unnecessary requests
• Multi-fingerprint Support: Isolated caches for different users/personalizations
• Cross-tab Synchronization: Optional broadcast channel sync between browser tabs
• UMD Bundle: Works everywhere - browser, Node.js, bundlers

Backend Compatibility

This SDK is compatible with backend changes:

• Backend returns single result field (instead of special / common)
• Backend returns special translation when fingerprint has entry, otherwise returns common

Changelog

1.2.5 (2026-04-08)

• Fix: 10 bug fixes addressing various issues in translation caching
• Fix: Improved error handling for network requests
• Fix: Corrected language code handling in multi-fingerprint scenarios
• Fix: Resolved race conditions in concurrent translation requests
• Fix: Fixed cross-tab synchronization channel naming
• Fix: Improved LRU cache eviction performance
• Fix: Corrected TypeScript type definitions for response parsing
• Fix: Fixed streaming translation connection handling
• Fix: Resolved memory leaks in long-running client instances
• Fix: Updated dependencies to latest versions
• Fix: Improved connection retry logic for failed requests

1.2.4 (2026-04-08)

• Fix: Translation pool now splits cache by language code
• Fix: Promise update and UI callback after translation pool completes loading
• Fix: Deferred Promise resolve for queued requests

1.2.3 (2026-03-28)

• Previous release with various improvements

License

MIT