@alaikis/translation-sdk 1.2.1 → 1.2.3

package/README.md

@@ -0,0 +1,195 @@
+# @alaikis/translation-sdk
+
+Laker Translation Service SDK for JavaScript/TypeScript - Simplified Single Entry Point
+
+## Installation
+
+```bash
+npm install @alaikis/translation-sdk
+```
+
+Or use directly in browser via CDN:
+
+```html
+<script src="https://unpkg.com/@alaikis/translation-sdk@latest/translation-client.js"></script>
+```
+
+## Quick Start
+
+### Browser (UMD Global)
+
+```html
+<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)
+
+```typescript
+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
+
+```typescript
+new TranslationClient(options: TranslationClientOptions)
+```
+
+**Options:**
+```typescript
+{
+  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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+async loadFingerprint(fingerprint: string): Promise<TranslationItem[]>
+```
+
+#### `getStats()`
+
+Get cache statistics.
+
+```typescript
+getStats(): string
+```
+
+#### `extractTemplate(text)`
+
+Extract template from text with numeric placeholders (e.g. `Page 1 of 10` → `Page %1 of %2`).
+
+```typescript
+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:**
+
+```typescript
+// 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:**
+
+```typescript
+// 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
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alaikis/translation-sdk",
-	"version": "1.2.1",
+	"version": "1.2.3",
 	"description": "Laker Translation Service SDK for TypeScript/JavaScript",
 	"main": "translation-client.js",
 	"types": "translation-client.d.ts",
@@ -8,6 +8,9 @@
 		"*.js",
 		"*.d.ts"
 	],
+	"scripts": {
+		"build": "npx tsc && npx rollup --config rollup.config.js"
+	},
 	"keywords": [
 		"translation",
 		"grpc-web",
@@ -24,5 +27,11 @@
 	"bugs": {
 		"url": "https://github.com/alaikis/laker-translate-sdk/issues"
 	},
-	"homepage": "https://github.com/alaikis/laker-translate-sdk#readme"
-}
+	"homepage": "https://github.com/alaikis/laker-translate-sdk#readme",
+	"devDependencies": {
+		"@rollup/plugin-typescript": "^12.3.0",
+		"rollup": "^4.60.0",
+		"tslib": "^2.8.1",
+		"typescript": "^6.0.2"
+	}
+}

package/rollup.config.js

@@ -0,0 +1,19 @@
+import typescript from '@rollup/plugin-typescript';
+
+export default {
+  input: 'translation-client.ts',
+  output: [
+    {
+      file: 'translation-client.js',
+      format: 'umd',
+      name: 'LakerTranslation',
+      sourcemap: false
+    }
+  ],
+  plugins: [typescript({
+    target: 'es2015',
+    declaration: true,
+    declarationDir: './',
+    strict: false
+  })]
+};