transduck 0.1.5 → 0.2.2

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/src/react/index.ts

@@ -1 +1,3 @@
+'use client';
+
 export { TransDuckProvider, t, ait, tPlural, aitPlural, useTransDuck, _resetReactState } from './provider.js';

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');
   });
 });

package/tests/providers.test.ts

@@ -0,0 +1,289 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  buildMessages,
+  buildPluralMessages,
+  buildSinglePrompt,
+  buildPluralSinglePrompt,
+  safeRender,
+} from '../src/providers/prompts.js';
+import { getProvider } from '../src/providers/index.js';
+import type { TransduckConfig } from '../src/config.js';
+import { loadConfig } from '../src/config.js';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+
+function makeConfig(overrides: Partial<TransduckConfig> = {}): TransduckConfig {
+  return {
+    projectName: 'test',
+    projectContext: 'A test site',
+    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,
+    ...overrides,
+  };
+}
+
+// ---- Prompts ----
+
+describe('prompts', () => {
+  describe('buildMessages', () => {
+    it('builds system and user messages', () => {
+      const messages = buildMessages({
+        sourceText: 'Hello',
+        sourceLang: 'EN',
+        targetLang: 'DE',
+        projectContext: 'A travel site',
+        stringContext: 'greeting',
+      });
+      expect(messages).toHaveLength(2);
+      expect(messages[0].role).toBe('system');
+      expect(messages[0].content).toContain('EN');
+      expect(messages[0].content).toContain('DE');
+      expect(messages[1].role).toBe('user');
+      expect(messages[1].content).toContain('Hello');
+      expect(messages[1].content).toContain('greeting');
+    });
+
+    it('uses "none" for null string context', () => {
+      const messages = buildMessages({
+        sourceText: 'Hello',
+        sourceLang: 'EN',
+        targetLang: 'DE',
+        projectContext: 'test',
+        stringContext: null,
+      });
+      expect(messages[1].content).toContain('none');
+    });
+  });
+
+  describe('buildPluralMessages', () => {
+    it('builds plural messages with CLDR info', () => {
+      const messages = buildPluralMessages({
+        one: '{count} item',
+        other: '{count} items',
+        sourceLang: 'EN',
+        targetLang: 'DE',
+        projectContext: 'test',
+        stringContext: null,
+      });
+      expect(messages).toHaveLength(2);
+      expect(messages[0].content).toContain('CLDR');
+      expect(messages[1].content).toContain('{count} item');
+      expect(messages[1].content).toContain('{count} items');
+    });
+  });
+
+  describe('buildSinglePrompt', () => {
+    it('combines system and user into one string', () => {
+      const prompt = buildSinglePrompt({
+        sourceText: 'Hello',
+        sourceLang: 'EN',
+        targetLang: 'DE',
+        projectContext: 'A travel site',
+        stringContext: 'greeting',
+      });
+      expect(prompt).toContain('EN');
+      expect(prompt).toContain('DE');
+      expect(prompt).toContain('Hello');
+      expect(prompt).toContain('greeting');
+    });
+  });
+
+  describe('buildPluralSinglePrompt', () => {
+    it('combines plural system and user into one string', () => {
+      const prompt = buildPluralSinglePrompt({
+        one: '{count} item',
+        other: '{count} items',
+        sourceLang: 'EN',
+        targetLang: 'DE',
+        projectContext: 'test',
+        stringContext: null,
+      });
+      expect(prompt).toContain('CLDR');
+      expect(prompt).toContain('{count} item');
+    });
+  });
+
+  describe('safeRender', () => {
+    it('replaces known keys only', () => {
+      const result = safeRender('Hello {name}, you have {count} items', {
+        name: 'Tim',
+      });
+      expect(result).toBe('Hello Tim, you have {count} items');
+    });
+  });
+});
+
+// ---- Provider router ----
+
+describe('getProvider', () => {
+  it('returns openai provider for openai config', async () => {
+    const openaiProvider = await import('../src/providers/openai-provider.js');
+    const provider = await getProvider(makeConfig({ provider: 'openai' }));
+    expect(provider.translate).toBe(openaiProvider.translate);
+    expect(provider.translatePlural).toBe(openaiProvider.translatePlural);
+  });
+
+  it('returns claude_api provider for claude_api config', async () => {
+    const claudeApiProvider = await import('../src/providers/claude-api.js');
+    const provider = await getProvider(makeConfig({ provider: 'claude_api' }));
+    expect(provider.translate).toBe(claudeApiProvider.translate);
+  });
+
+  it('returns claude_code provider for claude_code config', async () => {
+    const claudeCodeProvider = await import('../src/providers/claude-code.js');
+    const provider = await getProvider(makeConfig({ provider: 'claude_code' }));
+    expect(provider.translate).toBe(claudeCodeProvider.translate);
+  });
+
+  it('throws for invalid provider', async () => {
+    await expect(
+      getProvider(makeConfig({ provider: 'invalid' }))
+    ).rejects.toThrow('Unknown provider');
+  });
+});
+
+// ---- OpenAI provider ----
+
+describe('openai-provider', () => {
+  it('translate calls OpenAI and returns result', async () => {
+    const { translate } = await import('../src/providers/openai-provider.js');
+    const mockCreate = vi.fn().mockResolvedValue({
+      choices: [{ message: { content: 'Hallo' } }],
+    });
+
+    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');
+    expect(mockCreate).toHaveBeenCalledOnce();
+  });
+
+  it('translatePlural calls OpenAI and returns parsed JSON', async () => {
+    const { translatePlural } = await import('../src/providers/openai-provider.js');
+    const mockCreate = vi.fn().mockResolvedValue({
+      choices: [{ message: { content: '{"one": "{count} Nachricht", "other": "{count} Nachrichten"}' } }],
+    });
+
+    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',
+      other: '{count} Nachrichten',
+    });
+  });
+});
+
+// ---- Config with provider fields ----
+
+describe('config provider fields', () => {
+  it('defaults to openai provider', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'transduck-cfg-'));
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, `
+project:
+  name: test
+  context: "test"
+languages:
+  source: EN
+  targets: [DE]
+storage:
+  path: ./translations.duckdb
+backend:
+  api_key_env: OPENAI_API_KEY
+  model: gpt-4.1-mini
+  timeout_seconds: 10
+  max_retries: 2
+`);
+    const cfg = loadConfig(configPath);
+    expect(cfg.provider).toBe('openai');
+    expect(cfg.tokenEnv).toBe('CLAUDE_CODE_OAUTH_TOKEN');
+  });
+
+  it('loads claude_api provider', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'transduck-cfg-'));
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, `
+project:
+  name: test
+  context: "test"
+languages:
+  source: EN
+  targets: [DE]
+storage:
+  path: ./translations.duckdb
+backend:
+  provider: claude_api
+  api_key_env: ANTHROPIC_API_KEY
+  model: claude-haiku-4-5-20251001
+  timeout_seconds: 15
+  max_retries: 3
+`);
+    const cfg = loadConfig(configPath);
+    expect(cfg.provider).toBe('claude_api');
+    expect(cfg.apiKeyEnv).toBe('ANTHROPIC_API_KEY');
+    expect(cfg.backendModel).toBe('claude-haiku-4-5-20251001');
+  });
+
+  it('claude_code forces readOnly', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'transduck-cfg-'));
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, `
+project:
+  name: test
+  context: "test"
+languages:
+  source: EN
+  targets: [DE]
+storage:
+  path: ./translations.duckdb
+backend:
+  provider: claude_code
+  token_env: CLAUDE_CODE_OAUTH_TOKEN
+`);
+    const cfg = loadConfig(configPath);
+    expect(cfg.provider).toBe('claude_code');
+    expect(cfg.tokenEnv).toBe('CLAUDE_CODE_OAUTH_TOKEN');
+    expect(cfg.readOnly).toBe(true);
+  });
+
+  it('claude_code minimal config uses defaults', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'transduck-cfg-'));
+    const configPath = join(tmpDir, 'transduck.yaml');
+    writeFileSync(configPath, `
+project:
+  name: test
+  context: "test"
+languages:
+  source: EN
+  targets: [DE]
+storage:
+  path: ./translations.duckdb
+backend:
+  provider: claude_code
+`);
+    const cfg = loadConfig(configPath);
+    expect(cfg.provider).toBe('claude_code');
+    expect(cfg.readOnly).toBe(true);
+    expect(cfg.backendModel).toBe('gpt-4.1-mini');
+  });
+});