transduck 0.1.5 → 0.2.1

package/src/handler.ts

@@ -58,7 +58,6 @@ export async function handleTranslationRequest(
   const targetLang = body.language.toUpperCase();
 
   const projectContextHash = hash(cfg.projectContext);
-  const apiKey = process.env[cfg.apiKeyEnv];
 
   const translations: Record<string, string> = {};
   const plurals: Record<string, Record<string, string>> = {};
@@ -84,17 +83,14 @@ export async function handleTranslationRequest(
 
     // Backend call
     try {
-      const translated = await backendTranslate({
-        sourceText: item.text,
-        sourceLang: cfg.sourceLang,
+      const translated = await backendTranslate(
+        item.text,
+        cfg.sourceLang,
         targetLang,
-        projectContext: cfg.projectContext,
-        stringContext: item.context ?? null,
-        apiKey: apiKey!,
-        model: cfg.backendModel,
-        timeout: cfg.backendTimeout,
-        maxRetries: cfg.backendMaxRetries,
-      });
+        cfg.projectContext,
+        item.context ?? null,
+        cfg,
+      );
 
       if (validateTranslation(item.text, translated)) {
         await store.insert({
@@ -138,18 +134,15 @@ export async function handleTranslationRequest(
 
     // Backend call
     try {
-      const forms = await backendTranslatePlural({
-        one: item.one,
-        other: item.other,
-        sourceLang: cfg.sourceLang,
+      const forms = await backendTranslatePlural(
+        item.one,
+        item.other,
+        cfg.sourceLang,
         targetLang,
-        projectContext: cfg.projectContext,
-        stringContext: item.context ?? null,
-        apiKey: apiKey!,
-        model: cfg.backendModel,
-        timeout: cfg.backendTimeout,
-        maxRetries: cfg.backendMaxRetries,
-      });
+        cfg.projectContext,
+        item.context ?? null,
+        cfg,
+      );
 
       for (const [cat, translatedText] of Object.entries(forms)) {
         await store.insertPlural({

package/src/index.ts

@@ -92,14 +92,11 @@ export async function ait(
     });
     if (rechecked !== null) return rechecked;
 
-    const apiKey = process.env[cfg.apiKeyEnv];
     try {
-      const translated = await backendTranslate({
-        sourceText, sourceLang: cfg.sourceLang, targetLang: state.targetLang!,
-        projectContext: cfg.projectContext, stringContext: context ?? null,
-        apiKey: apiKey!, model: cfg.backendModel,
-        timeout: cfg.backendTimeout, maxRetries: cfg.backendMaxRetries,
-      });
+      const translated = await backendTranslate(
+        sourceText, cfg.sourceLang, state.targetLang!,
+        cfg.projectContext, context ?? null, cfg,
+      );
 
       if (!validateTranslation(sourceText, translated)) {
         console.warn(`[transduck] Validation failed for: ${sourceText} -> ${translated}`);
@@ -192,15 +189,12 @@ export async function aitPlural(
   }
 
   // Cache miss — call backend
-  const apiKey = process.env[cfg.apiKeyEnv];
   try {
-    const forms = await backendTranslatePlural({
+    const forms = await backendTranslatePlural(
       one, other,
-      sourceLang: cfg.sourceLang, targetLang: state.targetLang,
-      projectContext: cfg.projectContext, stringContext: context ?? null,
-      apiKey: apiKey!, model: cfg.backendModel,
-      timeout: cfg.backendTimeout, maxRetries: cfg.backendMaxRetries,
-    });
+      cfg.sourceLang, state.targetLang,
+      cfg.projectContext, context ?? null, cfg,
+    );
 
     // Validate and store each form
     const validCategories = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);

package/src/providers/claude-api.ts

@@ -0,0 +1,77 @@
+/**
+ * Claude API translation provider.
+ * Uses the @anthropic-ai/sdk package (optional peer dependency, lazy imported).
+ */
+
+import type { TransduckConfig } from '../config.js';
+import { buildMessages, buildPluralMessages } from './prompts.js';
+
+async function getClient(config: TransduckConfig) {
+  let Anthropic: any;
+  try {
+    // @ts-ignore — optional peer dependency, may not be installed
+    const mod = await import('@anthropic-ai/sdk');
+    Anthropic = mod.default ?? mod.Anthropic;
+  } catch {
+    throw new Error(
+      'Install the required package: npm install @anthropic-ai/sdk'
+    );
+  }
+
+  const apiKey = process.env[config.apiKeyEnv];
+  if (!apiKey) {
+    throw new Error(`Set ${config.apiKeyEnv} environment variable`);
+  }
+
+  return new Anthropic({ apiKey });
+}
+
+export async function translate(
+  sourceText: string,
+  sourceLang: string,
+  targetLang: string,
+  projectContext: string,
+  stringContext: string | null,
+  config: TransduckConfig,
+): Promise<string> {
+  const client = await getClient(config);
+  const messages = buildMessages({
+    sourceText, sourceLang, targetLang, projectContext, stringContext,
+  });
+
+  const response = await client.messages.create({
+    model: config.backendModel,
+    max_tokens: 1024,
+    temperature: 0.3,
+    system: messages[0].content,
+    messages: [{ role: 'user', content: messages[1].content }],
+  });
+
+  return response.content[0].text.trim();
+}
+
+export async function translatePlural(
+  one: string,
+  other: string,
+  sourceLang: string,
+  targetLang: string,
+  projectContext: string,
+  stringContext: string | null,
+  config: TransduckConfig,
+): Promise<Record<string, string>> {
+  const client = await getClient(config);
+  const messages = buildPluralMessages({
+    one, other, sourceLang, targetLang, projectContext, stringContext,
+  });
+
+  const response = await client.messages.create({
+    model: config.backendModel,
+    max_tokens: 2048,
+    temperature: 0.3,
+    system: messages[0].content,
+    messages: [{ role: 'user', content: messages[1].content }],
+  });
+
+  const raw = response.content[0].text.trim();
+  return JSON.parse(raw);
+}

package/src/providers/claude-code.ts

@@ -0,0 +1,72 @@
+/**
+ * Claude Code translation provider (uses Claude Agent SDK with subscription auth).
+ * Uses the @anthropic-ai/claude-agent-sdk package (optional peer dependency, lazy imported).
+ * Already async in JS — no asyncio bridge needed like Python.
+ */
+
+import type { TransduckConfig } from '../config.js';
+import { buildSinglePrompt, buildPluralSinglePrompt } from './prompts.js';
+
+function ensureToken(config: TransduckConfig): void {
+  const token = process.env[config.tokenEnv];
+  if (!token) {
+    throw new Error(
+      `Set ${config.tokenEnv} \u2014 run 'claude setup-token' to get your OAuth token`
+    );
+  }
+}
+
+async function translateWithSdk(prompt: string): Promise<string> {
+  let query: any;
+  try {
+    // @ts-ignore — optional peer dependency, may not be installed
+    const mod = await import('@anthropic-ai/claude-agent-sdk');
+    query = mod.query;
+  } catch {
+    throw new Error(
+      'Install the required package: npm install @anthropic-ai/claude-agent-sdk'
+    );
+  }
+
+  for await (const message of query({
+    prompt,
+    options: { allowedTools: [] },
+  })) {
+    if ('result' in message) {
+      return (message as any).result.trim();
+    }
+  }
+  throw new Error('No result from Claude Agent SDK');
+}
+
+export async function translate(
+  sourceText: string,
+  sourceLang: string,
+  targetLang: string,
+  projectContext: string,
+  stringContext: string | null,
+  config: TransduckConfig,
+): Promise<string> {
+  ensureToken(config);
+  const prompt = buildSinglePrompt({
+    sourceText, sourceLang, targetLang, projectContext, stringContext,
+  });
+  return translateWithSdk(prompt);
+}
+
+export async function translatePlural(
+  one: string,
+  other: string,
+  sourceLang: string,
+  targetLang: string,
+  projectContext: string,
+  stringContext: string | null,
+  config: TransduckConfig,
+): Promise<Record<string, string>> {
+  ensureToken(config);
+  const prompt = buildPluralSinglePrompt({
+    one, other, sourceLang, targetLang, projectContext, stringContext,
+  });
+  const raw = await translateWithSdk(prompt);
+  return JSON.parse(raw);
+}

package/src/providers/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Translation provider abstraction.
+ */
+
+import type { TransduckConfig } from '../config.js';
+
+export interface TranslationProvider {
+  translate(
+    sourceText: string,
+    sourceLang: string,
+    targetLang: string,
+    projectContext: string,
+    stringContext: string | null,
+    config: TransduckConfig,
+    _clientOverride?: any,
+  ): Promise<string>;
+
+  translatePlural(
+    one: string,
+    other: string,
+    sourceLang: string,
+    targetLang: string,
+    projectContext: string,
+    stringContext: string | null,
+    config: TransduckConfig,
+    _clientOverride?: any,
+  ): Promise<Record<string, string>>;
+}
+
+/**
+ * Return the provider module for the configured provider.
+ */
+export async function getProvider(config: TransduckConfig): Promise<TranslationProvider> {
+  if (config.provider === 'openai') {
+    return await import('./openai-provider.js');
+  } else if (config.provider === 'claude_api') {
+    return await import('./claude-api.js');
+  } else if (config.provider === 'claude_code') {
+    return await import('./claude-code.js');
+  } else {
+    throw new Error(
+      `Unknown provider: ${config.provider}. Valid: openai, claude_api, claude_code`
+    );
+  }
+}

package/src/providers/openai-provider.ts

@@ -0,0 +1,67 @@
+/**
+ * OpenAI translation provider.
+ */
+
+import OpenAI from 'openai';
+import type { TransduckConfig } from '../config.js';
+import { buildMessages, buildPluralMessages } from './prompts.js';
+
+export async function translate(
+  sourceText: string,
+  sourceLang: string,
+  targetLang: string,
+  projectContext: string,
+  stringContext: string | null,
+  config: TransduckConfig,
+  _clientOverride?: any,
+): Promise<string> {
+  const apiKey = process.env[config.apiKeyEnv];
+  const client = _clientOverride ?? new OpenAI({
+    apiKey,
+    timeout: config.backendTimeout * 1000,
+    maxRetries: config.backendMaxRetries,
+  });
+
+  const messages = buildMessages({
+    sourceText, sourceLang, targetLang, projectContext, stringContext,
+  });
+
+  const response = await client.chat.completions.create({
+    model: config.backendModel,
+    messages,
+    temperature: 0.3,
+  });
+
+  return response.choices[0].message.content.trim();
+}
+
+export async function translatePlural(
+  one: string,
+  other: string,
+  sourceLang: string,
+  targetLang: string,
+  projectContext: string,
+  stringContext: string | null,
+  config: TransduckConfig,
+  _clientOverride?: any,
+): Promise<Record<string, string>> {
+  const apiKey = process.env[config.apiKeyEnv];
+  const client = _clientOverride ?? new OpenAI({
+    apiKey,
+    timeout: config.backendTimeout * 1000,
+    maxRetries: config.backendMaxRetries,
+  });
+
+  const messages = buildPluralMessages({
+    one, other, sourceLang, targetLang, projectContext, stringContext,
+  });
+
+  const response = await client.chat.completions.create({
+    model: config.backendModel,
+    messages,
+    temperature: 0.3,
+  });
+
+  const raw = response.choices[0].message.content.trim();
+  return JSON.parse(raw);
+}

package/src/providers/prompts.ts

@@ -0,0 +1,124 @@
+/* eslint-disable no-template-curly-in-string */
+
+/**
+ * Shared prompt templates for all translation providers.
+ *
+ * IMPORTANT: Uses string concatenation (NOT template literals) because the
+ * prompt text contains ${value} patterns that must be preserved literally.
+ */
+
+const SYSTEM_TEMPLATE =
+  'You are a professional translator. Translate the given text from {source_lang} ' +
+  'to {target_lang}. Return ONLY the translated text, nothing else. Preserve any ' +
+  'placeholders like {name}, {{count}}, %s, ${value} exactly as they appear. ' +
+  'Preserve brand names. Match the tone and formality of the original.\n\n' +
+  'Project context: {project_context}';
+
+const USER_TEMPLATE =
+  'Translate: "{source_text}"\nString context: {string_context}';
+
+const PLURAL_SYSTEM_TEMPLATE =
+  'You are a professional translator. You will be given two plural forms ' +
+  '(one and other) in {source_lang}. Generate ALL plural forms needed in ' +
+  '{target_lang} according to CLDR plural rules. Return ONLY a JSON object ' +
+  'mapping plural categories to translated strings. Do not include explanation.\n\n' +
+  'CRITICAL: Placeholders like {count}, {name}, %s, ${value} are SOFTWARE VARIABLES ' +
+  'that will be replaced by code at runtime. You MUST include them exactly as written ' +
+  'in EVERY plural form, even for zero, one, and two categories where the language ' +
+  'would not normally use a numeral. For example, for Arabic zero: use "{count} ..." ' +
+  'not "\u0644\u0627 \u062a\u0648\u062c\u062f ...". For Arabic one: use "{count} ..." not "\u0648\u0627\u062d\u062f\u0629 ...".\n\n' +
+  'Preserve brand names. Match the tone and formality of the original.\n\n' +
+  'CLDR plural categories are: zero, one, two, few, many, other.\n' +
+  'Only include categories that {target_lang} actually uses.\n\n' +
+  'Project context: {project_context}';
+
+const PLURAL_USER_TEMPLATE =
+  'Source one form: "{one}"\n' +
+  'Source other form: "{other}"\n' +
+  'String context: {string_context}';
+
+/**
+ * Safe string replacement that only replaces known keys.
+ * Does NOT use str.replace with regex — avoids issues with ${value} patterns.
+ */
+export function safeRender(template: string, vars: Record<string, string>): string {
+  let result = template;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll('{' + key + '}', value);
+  }
+  return result;
+}
+
+export interface BuildMessagesParams {
+  sourceText: string;
+  sourceLang: string;
+  targetLang: string;
+  projectContext: string;
+  stringContext: string | null;
+}
+
+export interface BuildPluralMessagesParams {
+  one: string;
+  other: string;
+  sourceLang: string;
+  targetLang: string;
+  projectContext: string;
+  stringContext: string | null;
+}
+
+/**
+ * Build system + user messages for chat-based providers (OpenAI, Claude API).
+ */
+export function buildMessages(params: BuildMessagesParams): Array<{ role: string; content: string }> {
+  const systemMsg = SYSTEM_TEMPLATE
+    .replace('{source_lang}', params.sourceLang)
+    .replace('{target_lang}', params.targetLang)
+    .replace('{project_context}', params.projectContext);
+
+  const userMsg = USER_TEMPLATE
+    .replace('{source_text}', params.sourceText)
+    .replace('{string_context}', params.stringContext || 'none');
+
+  return [
+    { role: 'system', content: systemMsg },
+    { role: 'user', content: userMsg },
+  ];
+}
+
+/**
+ * Build system + user messages for plural chat-based providers.
+ */
+export function buildPluralMessages(params: BuildPluralMessagesParams): Array<{ role: string; content: string }> {
+  const systemMsg = safeRender(PLURAL_SYSTEM_TEMPLATE, {
+    source_lang: params.sourceLang,
+    target_lang: params.targetLang,
+    project_context: params.projectContext,
+  });
+
+  const userMsg = safeRender(PLURAL_USER_TEMPLATE, {
+    one: params.one,
+    other: params.other,
+    string_context: params.stringContext || 'none',
+  });
+
+  return [
+    { role: 'system', content: systemMsg },
+    { role: 'user', content: userMsg },
+  ];
+}
+
+/**
+ * Build a single combined prompt for non-chat providers (Claude Code).
+ */
+export function buildSinglePrompt(params: BuildMessagesParams): string {
+  const messages = buildMessages(params);
+  return messages[0].content + '\n\n' + messages[1].content;
+}
+
+/**
+ * Build a single combined plural prompt for non-chat providers.
+ */
+export function buildPluralSinglePrompt(params: BuildPluralMessagesParams): string {
+  const messages = buildPluralMessages(params);
+  return messages[0].content + '\n\n' + messages[1].content;
+}

package/tests/ait.test.ts

@@ -16,10 +16,13 @@ function makeConfig(tmpDir: string): TransduckConfig {
     sourceLang: 'EN',
     targetLangs: ['DE', 'ES'],
     storagePath: join(tmpDir, 'test.duckdb'),
+    provider: 'openai',
     apiKeyEnv: 'OPENAI_API_KEY',
+    tokenEnv: 'CLAUDE_CODE_OAUTH_TOKEN',
     backendModel: 'gpt-4.1-mini',
     backendTimeout: 10,
     backendMaxRetries: 2,
+    readOnly: false,
   };
 }
 

package/tests/backend.test.ts

@@ -1,5 +1,23 @@
 import { describe, it, expect, vi } from 'vitest';
-import { buildMessages, translate, buildPluralMessages, translatePlural } from '../src/backend.js';
+import { buildMessages, buildPluralMessages, translate, translatePlural } from '../src/backend.js';
+import type { TransduckConfig } from '../src/config.js';
+
+function makeConfig(): TransduckConfig {
+  return {
+    projectName: 'test',
+    projectContext: 'A travel site about Mallorca',
+    sourceLang: 'EN',
+    targetLangs: ['DE'],
+    storagePath: '/tmp/test.duckdb',
+    provider: 'openai',
+    apiKeyEnv: 'OPENAI_API_KEY',
+    tokenEnv: 'CLAUDE_CODE_OAUTH_TOKEN',
+    backendModel: 'gpt-4.1-mini',
+    backendTimeout: 10,
+    backendMaxRetries: 2,
+    readOnly: false,
+  };
+}
 
 describe('buildMessages', () => {
   it('builds system and user messages', () => {
@@ -38,18 +56,14 @@ describe('translate', () => {
       choices: [{ message: { content: 'Unsere Veranstaltungen' } }],
     });
 
-    const result = await translate({
-      sourceText: 'Our Events',
-      sourceLang: 'EN',
-      targetLang: 'DE',
-      projectContext: 'A travel site',
-      stringContext: null,
-      apiKey: 'test-key',
-      model: 'gpt-4.1-mini',
-      timeout: 10,
-      maxRetries: 2,
-      _clientOverride: { chat: { completions: { create: mockCreate } } } as any,
-    });
+    const cfg = makeConfig();
+    process.env.OPENAI_API_KEY = 'test-key';
+
+    const result = await translate(
+      'Our Events', 'EN', 'DE',
+      'A travel site', null, cfg,
+      { chat: { completions: { create: mockCreate } } } as any,
+    );
     expect(result).toBe('Unsere Veranstaltungen');
   });
 
@@ -58,18 +72,14 @@ describe('translate', () => {
       choices: [{ message: { content: '  Hallo  \n' } }],
     });
 
-    const result = await translate({
-      sourceText: 'Hello',
-      sourceLang: 'EN',
-      targetLang: 'DE',
-      projectContext: 'test',
-      stringContext: null,
-      apiKey: 'test-key',
-      model: 'gpt-4.1-mini',
-      timeout: 10,
-      maxRetries: 2,
-      _clientOverride: { chat: { completions: { create: mockCreate } } } as any,
-    });
+    const cfg = makeConfig();
+    process.env.OPENAI_API_KEY = 'test-key';
+
+    const result = await translate(
+      'Hello', 'EN', 'DE',
+      'test', null, cfg,
+      { chat: { completions: { create: mockCreate } } } as any,
+    );
     expect(result).toBe('Hallo');
   });
 });
@@ -132,19 +142,15 @@ describe('translatePlural', () => {
       choices: [{ message: { content: '{"one": "{count} Nachricht", "other": "{count} Nachrichten"}' } }],
     });
 
-    const result = await translatePlural({
-      one: '{count} message',
-      other: '{count} messages',
-      sourceLang: 'EN',
-      targetLang: 'DE',
-      projectContext: 'test',
-      stringContext: null,
-      apiKey: 'test-key',
-      model: 'gpt-4.1-mini',
-      timeout: 10,
-      maxRetries: 2,
-      _clientOverride: { chat: { completions: { create: mockCreate } } } as any,
-    });
+    const cfg = makeConfig();
+    process.env.OPENAI_API_KEY = 'test-key';
+
+    const result = await translatePlural(
+      '{count} message', '{count} messages',
+      'EN', 'DE',
+      'test', null, cfg,
+      { chat: { completions: { create: mockCreate } } } as any,
+    );
 
     expect(result).toEqual({
       one: '{count} Nachricht',
@@ -155,30 +161,26 @@ describe('translatePlural', () => {
   it('returns multiple categories for Russian', async () => {
     const mockCreate = vi.fn().mockResolvedValue({
       choices: [{ message: { content: JSON.stringify({
-        one: '{count} сообщение',
-        few: '{count} сообщения',
-        many: '{count} сообщений',
-        other: '{count} сообщений',
+        one: '{count} \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u0435',
+        few: '{count} \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u044f',
+        many: '{count} \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u0439',
+        other: '{count} \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u0439',
       }) } }],
     });
 
-    const result = await translatePlural({
-      one: '{count} message',
-      other: '{count} messages',
-      sourceLang: 'EN',
-      targetLang: 'RU',
-      projectContext: 'test',
-      stringContext: null,
-      apiKey: 'test-key',
-      model: 'gpt-4.1-mini',
-      timeout: 10,
-      maxRetries: 2,
-      _clientOverride: { chat: { completions: { create: mockCreate } } } as any,
-    });
+    const cfg = makeConfig();
+    process.env.OPENAI_API_KEY = 'test-key';
+
+    const result = await translatePlural(
+      '{count} message', '{count} messages',
+      'EN', 'RU',
+      'test', null, cfg,
+      { chat: { completions: { create: mockCreate } } } as any,
+    );
 
-    expect(result.one).toBe('{count} сообщение');
-    expect(result.few).toBe('{count} сообщения');
-    expect(result.many).toBe('{count} сообщений');
-    expect(result.other).toBe('{count} сообщений');
+    expect(result.one).toBe('{count} \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u0435');
+    expect(result.few).toBe('{count} \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u044f');
+    expect(result.many).toBe('{count} \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u0439');
+    expect(result.other).toBe('{count} \u0441\u043e\u043e\u0431\u0449\u0435\u043d\u0438\u0439');
   });
 });