dialekt 0.1.0

package/src/translation/prompt.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest';
+import { buildSystemPrompt, buildUserPrompt } from './prompt.js';
+
+describe('buildSystemPrompt', () => {
+  it('contains from and to language', () => {
+    const prompt = buildSystemPrompt('en', 'de');
+    expect(prompt).toContain('en');
+    expect(prompt).toContain('de');
+    expect(prompt).toContain('Do not escape Unicode');
+  });
+
+  it('mentions placeholder preservation', () => {
+    const prompt = buildSystemPrompt('en', 'ja');
+    expect(prompt).toContain(':attribute');
+    expect(prompt).toContain(':min');
+    expect(prompt).toContain(':max');
+  });
+
+  it('instructs to not add or remove keys', () => {
+    const prompt = buildSystemPrompt('en', 'fr');
+    expect(prompt).toContain('Do not add or remove keys');
+  });
+
+  it('mentions double quote escaping', () => {
+    const prompt = buildSystemPrompt('en', 'es');
+    expect(prompt).toContain('double quotes');
+  });
+
+  it('handles same-language translation edge case', () => {
+    const prompt = buildSystemPrompt('en', 'en');
+    expect(prompt).toContain('en');
+  });
+
+  it('handles long locale codes', () => {
+    const prompt = buildSystemPrompt('zh-Hans', 'zh-Hant');
+    expect(prompt).toContain('zh-Hans');
+    expect(prompt).toContain('zh-Hant');
+  });
+});
+
+describe('buildUserPrompt', () => {
+  it('contains XML tags and key list', () => {
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { hello: 'Hello' },
+      targetMap: {},
+      keys: ['hello'],
+    };
+    const prompt = buildUserPrompt(ctx);
+    expect(prompt).toContain('<source-file>');
+    expect(prompt).toContain('<existing-translations>');
+    expect(prompt).toContain('<keys-to-translate>');
+    expect(prompt).toContain('hello');
+    expect(prompt).toContain('Translate ALL keys');
+  });
+
+  it('includes existing translations for context', () => {
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { a: 'A', b: 'B' },
+      targetMap: { a: 'already translated' },
+      keys: ['b'],
+    };
+    const prompt = buildUserPrompt(ctx);
+    expect(prompt).toContain('already translated');
+    expect(prompt).toContain('"b"');
+  });
+
+  it('handles empty keys list', () => {
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { hello: 'Hello' },
+      targetMap: {},
+      keys: [],
+    };
+    const prompt = buildUserPrompt(ctx);
+    expect(prompt).toContain('<keys-to-translate>');
+    expect(prompt).toContain('{}');
+  });
+
+  it('handles keys with missing values in sourceMap', () => {
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { hello: 'Hello' },
+      targetMap: {},
+      keys: ['hello', 'missing'],
+    };
+    const prompt = buildUserPrompt(ctx);
+    expect(prompt).toContain('"missing"');
+    expect(prompt).toContain('""');
+  });
+
+  it('handles special characters in values', () => {
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'ja',
+      sourceMap: { greeting: 'Hello \n World \t!' },
+      targetMap: {},
+      keys: ['greeting'],
+    };
+    const prompt = buildUserPrompt(ctx);
+    expect(prompt).toContain('Hello');
+  });
+
+  it('handles unicode values', () => {
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'ja',
+      sourceMap: { emoji: 'Hello 🌍' },
+      targetMap: {},
+      keys: ['emoji'],
+    };
+    const prompt = buildUserPrompt(ctx);
+    expect(prompt).toContain('🌍');
+  });
+
+  it('includes multiple keys in keys-to-translate', () => {
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { a: 'A', b: 'B', c: 'C' },
+      targetMap: {},
+      keys: ['a', 'b', 'c'],
+    };
+    const prompt = buildUserPrompt(ctx);
+    expect(prompt).toContain('"a"');
+    expect(prompt).toContain('"b"');
+    expect(prompt).toContain('"c"');
+  });
+
+  it('round-trips JSON sourceMap without corruption', () => {
+    const sourceMap = { key: 'value with "quotes" and \\ backslash' };
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap,
+      targetMap: {},
+      keys: ['key'],
+    };
+    const prompt = buildUserPrompt(ctx);
+    const jsonMatch = prompt.match(/<source-file>\n([\s\S]*?)\n<\/source-file>/)?.[1];
+    expect(jsonMatch).toBeDefined();
+    expect(() => JSON.parse(jsonMatch!)).not.toThrow();
+  });
+});

package/src/translation/prompt.ts

@@ -0,0 +1,42 @@
+export function buildSystemPrompt(from: string, to: string): string {
+  return `You are a professional software translator specializing in application localization.
+You translate language strings from ${from} to ${to}.
+
+Rules:
+- Maintain consistent tone, formality, and terminology with existing translations.
+- Do not translate proper nouns, brand names, or technical identifiers unless localization is standard.
+- Preserve placeholders like :attribute, :min, :max, etc. Do not translate them.
+- Use the exact same placeholder format as the source string.
+- Return ONLY the requested keys. Do not add or remove keys.
+- Do not escape Unicode characters with \\u notation. Write them directly.
+- Escape double quotes in translations with a backslash when needed.`;
+}
+
+import type { TranslationContext } from './types.js';
+
+export function buildUserPrompt(ctx: TranslationContext): string {
+  const sourceJson = JSON.stringify(ctx.sourceMap, null, 2);
+  const targetJson = JSON.stringify(ctx.targetMap, null, 2);
+
+  const keysWithValues: Record<string, string> = {};
+  for (const key of ctx.keys) {
+    keysWithValues[key] = ctx.sourceMap[key] ?? '';
+  }
+  const keysJson = JSON.stringify(keysWithValues, null, 2);
+
+  return `Translate the following language strings from ${ctx.sourceLocale} to ${ctx.targetLocale}.
+
+<source-file>
+${sourceJson}
+</source-file>
+
+<existing-translations>
+${targetJson}
+</existing-translations>
+
+<keys-to-translate>
+${keysJson}
+</keys-to-translate>
+
+Translate ALL keys listed in <keys-to-translate>. Use the existing translations and source file as context for consistency.`;
+}

package/src/translation/tool-loop-strategy.test.ts

@@ -0,0 +1,279 @@
+import { describe, expect, it } from 'vitest';
+import { Effect, Either } from 'effect';
+import { MockLanguageModelV3 } from 'ai/test';
+import { createToolLoopStrategy } from './tool-loop-strategy.js';
+import { TranslationFailedError } from './types.js';
+
+describe('createToolLoopStrategy', () => {
+  it('returns translated map when tool is called', async () => {
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => ({
+        text: '',
+        content: [
+          {
+            type: 'tool-call',
+            toolCallId: 'call-1',
+            toolName: 'submitTranslations',
+            input: JSON.stringify({ hello: 'Hallo', bye: 'Tschüss' }),
+          },
+        ],
+        finishReason: { unified: 'tool-calls' as const, raw: 'tool_calls' },
+        usage: {
+          inputTokens: { total: 10, noCache: 10, cacheRead: 0, cacheWrite: 0 },
+          outputTokens: { total: 4, text: 0, reasoning: 0 },
+        },
+        response: {
+          modelId: 'mock',
+          timestamp: new Date(),
+        },
+        request: { body: {} },
+        warnings: [],
+      }),
+    });
+
+    const strategy = createToolLoopStrategy({
+      model,
+      retry: { maxAttempts: 3, baseDelayMs: 10 },
+    });
+
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { hello: 'Hello', bye: 'Bye' },
+      targetMap: {},
+      keys: ['hello', 'bye'],
+    };
+
+    const result = await Effect.runPromise(strategy.translateChunk(ctx));
+    expect(result).toEqual({ hello: 'Hallo', bye: 'Tschüss' });
+  });
+
+  it('retries when tool is not called and fails after exhaustion', async () => {
+    let calls = 0;
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => {
+        calls++;
+        return {
+          text: '',
+          content: [{ type: 'text' as const, text: 'I will translate now' }],
+          finishReason: { unified: 'stop' as const, raw: 'stop' },
+          usage: {
+            inputTokens: { total: 10, noCache: 10, cacheRead: 0, cacheWrite: 0 },
+            outputTokens: { total: 2, text: 2, reasoning: 0 },
+          },
+          response: {
+            modelId: 'mock',
+            timestamp: new Date(),
+          },
+          request: { body: {} },
+          warnings: [],
+        };
+      },
+    });
+
+    const strategy = createToolLoopStrategy({
+      model,
+      retry: { maxAttempts: 2, baseDelayMs: 10 },
+    });
+
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { hello: 'Hello', bye: 'Bye' },
+      targetMap: {},
+      keys: ['hello', 'bye'],
+    };
+
+    const exit = await Effect.runPromise(Effect.either(strategy.translateChunk(ctx))) as Either.Either<unknown, TranslationFailedError>;
+    expect(calls).toBeGreaterThan(1);
+    if (exit._tag === 'Left') {
+      expect(exit.left._tag).toBe('TranslationFailedError');
+    } else {
+      throw new Error('Expected Left');
+    }
+  });
+
+  it('handles empty keys', async () => {
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => ({
+        text: '',
+        content: [{
+          type: 'tool-call',
+          toolCallId: 'call-1',
+          toolName: 'submitTranslations',
+          input: JSON.stringify({}),
+        }],
+        finishReason: { unified: 'tool-calls' as const, raw: 'tool_calls' },
+        usage: { inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 }, outputTokens: { total: 1, text: 0, reasoning: 0 } },
+        response: { modelId: 'mock', timestamp: new Date() },
+        request: { body: {} },
+        warnings: [],
+      }),
+    });
+
+    const strategy = createToolLoopStrategy({
+      model,
+      retry: { maxAttempts: 1, baseDelayMs: 10 },
+    });
+
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: {},
+      targetMap: {},
+      keys: [],
+    };
+
+    const result = await Effect.runPromise(strategy.translateChunk(ctx));
+    expect(result).toEqual({});
+  });
+
+  it('handles wrong tool name by retrying', async () => {
+    let calls = 0;
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => {
+        calls++;
+        return {
+          text: '',
+          content: [{
+            type: 'tool-call',
+            toolCallId: 'call-1',
+            toolName: calls < 2 ? 'wrongTool' : 'submitTranslations',
+            input: JSON.stringify({ k: 'v' }),
+          }],
+          finishReason: { unified: 'tool-calls' as const, raw: 'tool_calls' },
+          usage: { inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 }, outputTokens: { total: 1, text: 0, reasoning: 0 } },
+          response: { modelId: 'mock', timestamp: new Date() },
+          request: { body: {} },
+          warnings: [],
+        };
+      },
+    });
+
+    const strategy = createToolLoopStrategy({
+      model,
+      retry: { maxAttempts: 3, baseDelayMs: 10 },
+    });
+
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { k: 'K' },
+      targetMap: {},
+      keys: ['k'],
+    };
+
+    const result = await Effect.runPromise(strategy.translateChunk(ctx));
+    expect(result).toEqual({ k: 'v' });
+    expect(calls).toBeGreaterThan(1);
+  });
+
+  it('handles malformed tool input by retrying', async () => {
+    let calls = 0;
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => {
+        calls++;
+        return {
+          text: '',
+          content: [{
+            type: 'tool-call',
+            toolCallId: 'call-1',
+            toolName: 'submitTranslations',
+            input: calls < 2 ? 'not-json' : JSON.stringify({ k: 'v' }),
+          }],
+          finishReason: { unified: 'tool-calls' as const, raw: 'tool_calls' },
+          usage: { inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 }, outputTokens: { total: 1, text: 0, reasoning: 0 } },
+          response: { modelId: 'mock', timestamp: new Date() },
+          request: { body: {} },
+          warnings: [],
+        };
+      },
+    });
+
+    const strategy = createToolLoopStrategy({
+      model,
+      retry: { maxAttempts: 3, baseDelayMs: 10 },
+    });
+
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { k: 'K' },
+      targetMap: {},
+      keys: ['k'],
+    };
+
+    const result = await Effect.runPromise(strategy.translateChunk(ctx));
+    expect(result).toEqual({ k: 'v' });
+    expect(calls).toBeGreaterThan(1);
+  });
+
+  it('fails after all retries when tool never called', async () => {
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => ({
+        text: '',
+        content: [{ type: 'text', text: 'I will translate now' }],
+        finishReason: { unified: 'stop' as const, raw: 'stop' },
+        usage: { inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 }, outputTokens: { total: 1, text: 1, reasoning: 0 } },
+        response: { modelId: 'mock', timestamp: new Date() },
+        request: { body: {} },
+        warnings: [],
+      }),
+    });
+
+    const strategy = createToolLoopStrategy({
+      model,
+      retry: { maxAttempts: 2, baseDelayMs: 10 },
+    });
+
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { k: 'K' },
+      targetMap: {},
+      keys: ['k'],
+    };
+
+    const exit = await Effect.runPromise(Effect.either(strategy.translateChunk(ctx))) as Either.Either<unknown, TranslationFailedError>;
+    if (exit._tag === 'Left') {
+      expect(exit.left._tag).toBe('TranslationFailedError');
+    } else {
+      throw new Error('Expected Left');
+    }
+  });
+
+  it('handles single key', async () => {
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => ({
+        text: '',
+        content: [{
+          type: 'tool-call',
+          toolCallId: 'call-1',
+          toolName: 'submitTranslations',
+          input: JSON.stringify({ greeting: 'Hallo' }),
+        }],
+        finishReason: { unified: 'tool-calls' as const, raw: 'tool_calls' },
+        usage: { inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 }, outputTokens: { total: 1, text: 0, reasoning: 0 } },
+        response: { modelId: 'mock', timestamp: new Date() },
+        request: { body: {} },
+        warnings: [],
+      }),
+    });
+
+    const strategy = createToolLoopStrategy({
+      model,
+      retry: { maxAttempts: 1, baseDelayMs: 10 },
+    });
+
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { greeting: 'Hello' },
+      targetMap: {},
+      keys: ['greeting'],
+    };
+
+    const result = await Effect.runPromise(strategy.translateChunk(ctx));
+    expect(result).toEqual({ greeting: 'Hallo' });
+  });
+});

package/src/translation/tool-loop-strategy.ts

@@ -0,0 +1,68 @@
+import { ToolLoopAgent, tool, hasToolCall } from 'ai';
+import { Effect, Schedule } from 'effect';
+import { z } from 'zod';
+import type { LanguageModel } from 'ai';
+import type { TranslationContext, TranslationStrategy } from './types.js';
+import { TranslationFailedError } from './types.js';
+import { buildSystemPrompt, buildUserPrompt } from './prompt.js';
+
+async function tryTranslateChunk(
+  model: LanguageModel,
+  ctx: TranslationContext,
+): Promise<Record<string, string>> {
+  const schema = z.object(
+    Object.fromEntries(ctx.keys.map((key: string) => [key, z.string()])),
+  );
+
+  let captured: Record<string, string> | null = null;
+
+  const submitTranslations = tool({
+    description:
+      'Submit the final translations for every requested key. Call this exactly once, with every key filled in.',
+    inputSchema: schema,
+    execute: async (input) => {
+      captured = input as Record<string, string>;
+      return { ok: true };
+    },
+  });
+
+  const agent = new ToolLoopAgent({
+    model,
+    instructions: buildSystemPrompt(ctx.sourceLocale, ctx.targetLocale),
+    tools: { submitTranslations },
+    stopWhen: hasToolCall('submitTranslations'),
+  });
+
+  await agent.generate({ prompt: buildUserPrompt(ctx) });
+  if (captured === null) {
+    throw new Error('Agent finished without calling submitTranslations');
+  }
+  const missing = ctx.keys.filter(
+    (key: string) => !(key in (captured as Record<string, string>)),
+  );
+  if (missing.length > 0) {
+    throw new Error(`Model omitted keys: ${missing.join(', ')}`);
+  }
+  return captured;
+}
+
+export function createToolLoopStrategy(deps: {
+  model: LanguageModel;
+  retry: { maxAttempts: number; baseDelayMs: number };
+}): TranslationStrategy {
+  return {
+    name: 'tool-loop-agent',
+    translateChunk: (ctx: TranslationContext) =>
+      Effect.tryPromise({
+        try: () => tryTranslateChunk(deps.model, ctx),
+        catch: (cause) => cause,
+      }).pipe(
+        Effect.retry(
+          Schedule.exponential(`${deps.retry.baseDelayMs} millis`).pipe(
+            Schedule.compose(Schedule.recurs(deps.retry.maxAttempts - 1)),
+          ),
+        ),
+        Effect.mapError((cause) => new TranslationFailedError({ keys: ctx.keys, cause })),
+      ),
+  };
+}

package/src/translation/types.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { TranslationFailedError } from './types.js';
+
+describe('TranslationFailedError', () => {
+  it('carries keys and cause', () => {
+    const err = new TranslationFailedError({ keys: ['a'], cause: new Error('boom') });
+    expect(err._tag).toBe('TranslationFailedError');
+    expect(err.keys).toEqual(['a']);
+  });
+
+  it('carries multiple keys', () => {
+    const err = new TranslationFailedError({ keys: ['a', 'b', 'c'], cause: 'network timeout' });
+    expect(err.keys).toEqual(['a', 'b', 'c']);
+  });
+
+  it('accepts string cause', () => {
+    const err = new TranslationFailedError({ keys: ['x'], cause: 'rate limited' });
+    expect(err._tag).toBe('TranslationFailedError');
+  });
+
+  it('accepts Error cause', () => {
+    const cause = new Error('model rejected');
+    const err = new TranslationFailedError({ keys: ['y'], cause });
+    expect(err._tag).toBe('TranslationFailedError');
+  });
+
+  it('accepts empty keys array', () => {
+    const err = new TranslationFailedError({ keys: [], cause: 'unknown' });
+    expect(err.keys).toEqual([]);
+  });
+
+  it('preserves cause object identity when Error', () => {
+    const cause = new Error('specific');
+    const err = new TranslationFailedError({ keys: ['z'], cause });
+    expect(err.cause).toBe(cause);
+  });
+});

package/src/translation/types.ts

@@ -0,0 +1,21 @@
+import { Data, Effect } from 'effect';
+
+export interface TranslationContext {
+  readonly sourceLocale: string;
+  readonly targetLocale: string;
+  readonly sourceMap: Record<string, string>; // full source resource, for context
+  readonly targetMap: Record<string, string>; // full existing target resource, for context
+  readonly keys: readonly string[]; // the specific keys to translate in this call
+}
+
+export class TranslationFailedError extends Data.TaggedError('TranslationFailedError')<{
+  readonly keys: readonly string[];
+  readonly cause: unknown;
+}> {}
+
+export interface TranslationStrategy {
+  readonly name: 'one-shot' | 'tool-loop-agent';
+  translateChunk(
+    ctx: TranslationContext,
+  ): Effect.Effect<Record<string, string>, TranslationFailedError>;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": []
+}