dialekt 0.1.0

package/src/translation/one-shot-strategy.test.ts

@@ -0,0 +1,259 @@
+import { describe, expect, it } from 'vitest';
+import { Effect, Either } from 'effect';
+import { MockLanguageModelV3 } from 'ai/test';
+import { createOneShotStrategy } from './one-shot-strategy.js';
+import { TranslationFailedError } from './types.js';
+
+describe('createOneShotStrategy', () => {
+  it('returns translated map on success', async () => {
+    const model = new MockLanguageModelV3({
+      doGenerate: async (options: { prompt: unknown }) => {
+        return {
+          text: '',
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ hello: 'Hallo', bye: 'Tschüss' }),
+            },
+          ],
+          finishReason: { unified: 'stop' as const, raw: 'stop' },
+          usage: {
+            inputTokens: { total: 10, noCache: 10, cacheRead: 0, cacheWrite: 0 },
+            outputTokens: { total: 4, text: 4, reasoning: 0 },
+          },
+          response: {
+            modelId: 'mock',
+            timestamp: new Date(),
+          },
+          request: { body: {} },
+          warnings: [],
+        };
+      },
+    });
+
+    const strategy = createOneShotStrategy({
+      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 model omits a key and fails after exhaustion', async () => {
+    let calls = 0;
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => {
+        calls++;
+        return {
+          text: '',
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ hello: 'Hallo' }),
+            },
+          ],
+          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 = createOneShotStrategy({
+      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: 'text', text: JSON.stringify({}) }],
+        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 = createOneShotStrategy({
+      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 malformed JSON response by retrying', async () => {
+    let calls = 0;
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => {
+        calls++;
+        return {
+          text: '',
+          content: [{ type: 'text', text: calls < 2 ? 'not-json' : JSON.stringify({ k: 'v' }) }],
+          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 = createOneShotStrategy({
+      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 exhausted', async () => {
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => ({
+        text: '',
+        content: [{ type: 'text', text: 'not-json' }],
+        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 = createOneShotStrategy({
+      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 model returning extra keys (ignores them)', async () => {
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => ({
+        text: '',
+        content: [{ type: 'text', text: JSON.stringify({ hello: 'Hallo', extra: 'ignored' }) }],
+        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 = createOneShotStrategy({
+      model,
+      retry: { maxAttempts: 1, baseDelayMs: 10 },
+    });
+
+    const ctx = {
+      sourceLocale: 'en',
+      targetLocale: 'de',
+      sourceMap: { hello: 'Hello' },
+      targetMap: {},
+      keys: ['hello'],
+    };
+
+    const result = await Effect.runPromise(strategy.translateChunk(ctx));
+    expect(result).toEqual({ hello: 'Hallo' });
+  });
+
+  it('handles single key translation', async () => {
+    const model = new MockLanguageModelV3({
+      doGenerate: async () => ({
+        text: '',
+        content: [{ type: 'text', text: JSON.stringify({ greeting: 'Hallo' }) }],
+        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 = createOneShotStrategy({
+      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/one-shot-strategy.ts

@@ -0,0 +1,48 @@
+import { generateText, Output } 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()])),
+  );
+  const { output } = await generateText({
+    model,
+    system: buildSystemPrompt(ctx.sourceLocale, ctx.targetLocale),
+    prompt: buildUserPrompt(ctx),
+    output: Output.object({ schema }),
+  });
+  const missing = ctx.keys.filter((key: string) => !(key in output));
+  if (missing.length > 0) {
+    throw new Error(`Model omitted keys: ${missing.join(', ')}`);
+  }
+  return output as Record<string, string>;
+}
+
+export function createOneShotStrategy(deps: {
+  model: LanguageModel;
+  retry: { maxAttempts: number; baseDelayMs: number };
+}): TranslationStrategy {
+  return {
+    name: 'one-shot',
+    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/orchestrator.test.ts

@@ -0,0 +1,276 @@
+import { describe, expect, it } from 'vitest';
+import { Effect, Either } from 'effect';
+import { runTranslation } from './orchestrator.js';
+import type { TranslationAdapter, ResourceRef, AdapterReadError, AdapterWriteError } from '../adapter/types.js';
+import { TranslationFailedError } from './types.js';
+
+describe('runTranslation', () => {
+  it('translates missing keys across adapters and writes merged results', async () => {
+    const writes: Array<{ locale: string; resource: string; entries: Record<string, string> }> = [];
+
+    const adapter: TranslationAdapter = {
+      name: 'test',
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.succeed(['en', 'de']),
+      listResources: () =>
+        Effect.succeed([{ key: 'messages', label: 'messages' }]),
+      readResource: (locale: string) =>
+        Effect.succeed(
+          locale === 'en'
+            ? { hello: 'Hello', bye: 'Bye' }
+            : { hello: 'Hallo' },
+        ),
+      writeResource: (locale: string, resource: ResourceRef, entries: Record<string, string>) =>
+        Effect.sync(() => {
+          writes.push({ locale, resource: resource.key, entries });
+        }),
+    };
+
+    const strategy = {
+      name: 'one-shot' as const,
+      translateChunk: (ctx: { keys: readonly string[]; targetLocale: string }) =>
+        Effect.succeed(
+          Object.fromEntries(ctx.keys.map((k: string) => [k, `${ctx.targetLocale}:${k}`])),
+        ),
+    };
+
+    const program = runTranslation({
+      adapters: [adapter],
+      strategy,
+      sourceLocale: 'en',
+      targetLocales: ['de'],
+      chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+    });
+
+    await Effect.runPromise(program);
+    expect(writes).toHaveLength(1);
+    expect(writes[0]!.locale).toBe('de');
+    expect(writes[0]!.entries).toEqual({ hello: 'Hallo', bye: 'de:bye' });
+  });
+
+  it('respects concurrency limit', async () => {
+    let maxConcurrent = 0;
+    let current = 0;
+
+    const adapter: TranslationAdapter = {
+      name: 'test',
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.succeed(['en', 'de']),
+      listResources: () =>
+        Effect.succeed([{ key: 'messages', label: 'messages' }]),
+      readResource: (locale: string) =>
+        Effect.succeed(
+          locale === 'en'
+            ? { a: 'A', b: 'B', c: 'C', d: 'D' }
+            : {},
+        ),
+      writeResource: () => Effect.void,
+    };
+
+    const strategy = {
+      name: 'one-shot' as const,
+      translateChunk: (ctx: { keys: readonly string[] }) =>
+        Effect.gen(function* () {
+          current++;
+          maxConcurrent = Math.max(maxConcurrent, current);
+          yield* Effect.sleep('50 millis');
+          current--;
+          return Object.fromEntries(ctx.keys.map((k: string) => [k, k]));
+        }),
+    };
+
+    const program = runTranslation({
+      adapters: [adapter],
+      strategy,
+      sourceLocale: 'en',
+      targetLocales: ['de'],
+      chunking: { maxTokens: 10, charsPerToken: 3.0, concurrency: 2 },
+    });
+
+    await Effect.runPromise(program);
+    expect(maxConcurrent).toBeLessThanOrEqual(2);
+  });
+
+  it('collects failures and reports them at the end', async () => {
+    const adapter: TranslationAdapter = {
+      name: 'test',
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.succeed(['en', 'de']),
+      listResources: () =>
+        Effect.succeed([{ key: 'messages', label: 'messages' }]),
+      readResource: (locale: string) =>
+        Effect.succeed(
+          locale === 'en' ? { a: 'A' } : {},
+        ),
+      writeResource: () => Effect.void,
+    };
+
+    const strategy = {
+      name: 'one-shot' as const,
+      translateChunk: () =>
+        Effect.fail(
+          new TranslationFailedError({ keys: ['a'], cause: 'boom' }),
+        ),
+    };
+
+    const program = runTranslation({
+      adapters: [adapter],
+      strategy,
+      sourceLocale: 'en',
+      targetLocales: ['de'],
+      chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+    });
+
+    const exit = await Effect.runPromise(Effect.either(program)) as Either.Either<void, TranslationFailedError>;
+    if (exit._tag === 'Left') {
+      expect((exit.left as TranslationFailedError)._tag).toBe('TranslationFailedError');
+    } else {
+      throw new Error('Expected Left');
+    }
+  });
+
+  it('handles empty adapters list', async () => {
+    const strategy = {
+      name: 'one-shot' as const,
+      translateChunk: () => Effect.succeed({}),
+    };
+
+    const program = runTranslation({
+      adapters: [],
+      strategy,
+      sourceLocale: 'en',
+      targetLocales: ['de'],
+      chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+    });
+
+    await Effect.runPromise(program);
+    expect(true).toBe(true); // should not throw
+  });
+
+  it('handles single-locale adapter (no targets)', async () => {
+    const adapter: TranslationAdapter = {
+      name: 'mono',
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.succeed(['en']),
+      listResources: () => Effect.succeed([{ key: 'messages', label: 'messages' }]),
+      readResource: () => Effect.succeed({ hello: 'Hello' }),
+      writeResource: () => Effect.void,
+    };
+
+    const strategy = {
+      name: 'one-shot' as const,
+      translateChunk: () => Effect.succeed({}),
+    };
+
+    const program = runTranslation({
+      adapters: [adapter],
+      strategy,
+      sourceLocale: 'en',
+      targetLocales: ['de'],
+      chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+    });
+
+    await Effect.runPromise(program);
+    expect(true).toBe(true); // should not throw
+  });
+
+  it('handles multiple resources', async () => {
+    const writes: Array<{ locale: string; resource: string }> = [];
+    const adapter: TranslationAdapter = {
+      name: 'multi',
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.succeed(['en', 'de']),
+      listResources: () =>
+        Effect.succeed([
+          { key: 'auth', label: 'auth' },
+          { key: 'validation', label: 'validation' },
+        ]),
+      readResource: (locale: string) =>
+        Effect.succeed(
+          locale === 'en' ? { k1: 'V1' } : {},
+        ),
+      writeResource: (locale: string, resource: ResourceRef) =>
+        Effect.sync(() => {
+          writes.push({ locale, resource: resource.key });
+        }),
+    };
+
+    const strategy = {
+      name: 'one-shot' as const,
+      translateChunk: (ctx: { keys: readonly string[] }) =>
+        Effect.succeed(Object.fromEntries(ctx.keys.map((k: string) => [k, k]))),
+    };
+
+    const program = runTranslation({
+      adapters: [adapter],
+      strategy,
+      sourceLocale: 'en',
+      targetLocales: ['de'],
+      chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+    });
+
+    await Effect.runPromise(program);
+    expect(writes.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('handles adapter readResource failure', async () => {
+    const adapter: TranslationAdapter = {
+      name: 'broken',
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.succeed(['en', 'de']),
+      listResources: () => Effect.succeed([{ key: 'messages', label: 'messages' }]),
+      readResource: () => Effect.fail(new Error('read failed') as AdapterReadError),
+      writeResource: () => Effect.void,
+    };
+
+    const strategy = {
+      name: 'one-shot' as const,
+      translateChunk: () => Effect.succeed({}),
+    };
+
+    const program = runTranslation({
+      adapters: [adapter],
+      strategy,
+      sourceLocale: 'en',
+      targetLocales: ['de'],
+      chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+    });
+
+    await expect(Effect.runPromise(program)).rejects.toThrow('read failed');
+  });
+
+  it('handles multiple target locales', async () => {
+    const writes: Array<{ locale: string }> = [];
+    const adapter: TranslationAdapter = {
+      name: 'multi-locale',
+      capabilities: { canCreateResource: true, unusedKeyDetection: false },
+      listLocales: () => Effect.succeed(['en', 'de', 'fr']),
+      listResources: () => Effect.succeed([{ key: 'messages', label: 'messages' }]),
+      readResource: (locale: string) =>
+        Effect.succeed(locale === 'en' ? { hello: 'Hello' } : {}),
+      writeResource: (locale: string) =>
+        Effect.sync(() => {
+          writes.push({ locale });
+        }),
+    };
+
+    const strategy = {
+      name: 'one-shot' as const,
+      translateChunk: (ctx: { keys: readonly string[]; targetLocale: string }) =>
+        Effect.succeed(Object.fromEntries(ctx.keys.map((k: string) => [k, `${ctx.targetLocale}:${k}`]))),
+    };
+
+    const program = runTranslation({
+      adapters: [adapter],
+      strategy,
+      sourceLocale: 'en',
+      targetLocales: ['de', 'fr'],
+      chunking: { maxTokens: 3000, charsPerToken: 3.0, concurrency: 3 },
+    });
+
+    await Effect.runPromise(program);
+    const locales = writes.map((w) => w.locale);
+    expect(locales).toContain('de');
+    expect(locales).toContain('fr');
+  });
+});

package/src/translation/orchestrator.ts

@@ -0,0 +1,83 @@
+import { Effect } from 'effect';
+import { chunkKeys } from './chunking.js';
+import { diffKeys } from '../keys/flatten.js';
+import type { TranslationAdapter } from '../adapter/types.js';
+import type { TranslationStrategy } from './types.js';
+import { TranslationFailedError } from './types.js';
+import type { ChunkingConfig } from '../config/types.js';
+
+export interface TranslationRunConfig {
+  readonly adapters: readonly TranslationAdapter[];
+  readonly strategy: TranslationStrategy;
+  readonly sourceLocale: string;
+  readonly targetLocales: readonly string[];
+  readonly chunking: ChunkingConfig;
+}
+
+export function runTranslation(config: TranslationRunConfig) {
+  return Effect.gen(function* () {
+    const failures: TranslationFailedError[] = [];
+
+    for (const adapter of config.adapters) {
+      const locales =
+        config.targetLocales.length > 0
+          ? config.targetLocales
+          : yield* adapter.listLocales();
+      const sourceLocale = config.sourceLocale;
+      const targetLocales = locales.filter((l: string) => l !== sourceLocale);
+
+      for (const locale of targetLocales) {
+        const resources = yield* adapter.listResources(sourceLocale);
+        for (const resource of resources) {
+          const sourceMap = yield* adapter.readResource(sourceLocale, resource);
+          const targetMap = yield* adapter.readResource(locale, resource);
+          const missing = diffKeys(sourceMap, targetMap);
+          if (missing.length === 0) continue;
+
+          const chunks = chunkKeys(missing, sourceMap, targetMap, {
+            maxTokens: config.chunking.maxTokens,
+            charsPerToken: config.chunking.charsPerToken,
+          });
+
+          const translatedChunks: Record<string, string>[] = [];
+
+          yield* Effect.forEach(chunks, (chunkKeysArr) =>
+            Effect.gen(function* () {
+              const result = yield* config.strategy.translateChunk({
+                sourceLocale,
+                targetLocale: locale,
+                sourceMap,
+                targetMap,
+                keys: chunkKeysArr,
+              });
+              translatedChunks.push(result);
+            }).pipe(
+              Effect.catchAll((err) => {
+                failures.push(err);
+                return Effect.void;
+              }),
+            ),
+            { concurrency: config.chunking.concurrency, discard: true },
+          );
+
+          const merged = { ...targetMap };
+          for (const chunk of translatedChunks) {
+            Object.assign(merged, chunk);
+          }
+          yield* adapter.writeResource(locale, resource, merged);
+        }
+      }
+    }
+
+    if (failures.length > 0) {
+      return yield* Effect.fail(
+        new TranslationFailedError({
+          keys: failures.flatMap((f) => [...f.keys]),
+          cause: failures.map((f) => f.cause),
+        }),
+      );
+    }
+
+    return void 0;
+  });
+}