@cgaravitoq/i18n-ai 0.2.3

package/README.md

@@ -0,0 +1,134 @@
+# i18n-ai
+
+AI-powered internationalization (i18n) translation and synchronization library. This tool automates the translation of your JSON message files using AI, keeping them synchronized with your base locale.
+
+## Features
+
+- 🤖 **AI-Powered**: Uses Google Gemini (via OpenRouter) to generate context-aware translations.
+- ⚡ **Parallel Processing**: Translations run concurrently for maximum speed (5x faster).
+- 🔄 **Smart Synchronization**: Detects new, modified, and obsolete keys.
+- ⛔ **Variable Protection**: Automatically preserves variables like `{name}` or `{count}`.
+- 🔒 **Lock File System**: Prevents unnecessary re-translations of already translated content.
+- 🧩 **Framework Agnostic**: Works with any i18n library that uses JSON files (next-intl, react-i18next, etc.).
+
+## Installation
+
+```bash
+bun add @ccgp/i18n-ai
+# or
+npm install @ccgp/i18n-ai
+```
+
+## Usage
+
+### CLI
+
+The easiest way to use `i18n-ai` is via the CLI.
+
+1. **Initialize configuration:**
+
+```bash
+bun x i18n-ai init
+```
+
+This will create an `i18n-ai.config.json` file:
+
+```json
+{
+  "defaultLocale": "en",
+  "locales": ["en", "es", "fr"],
+  "messagesDir": "messages"
+}
+```
+
+2. **Run synchronization:**
+
+```bash
+bun x i18n-ai sync
+```
+
+### CLI Options
+
+The `sync` command supports these options:
+
+| Option | Description |
+|--------|-------------|
+| `-d, --dir <path>` | Messages directory (default: `messages`) |
+| `-l, --locales <items>` | Comma-separated list of locales |
+| `--default <locale>` | Default locale (default: `en`) |
+| `--lock <path>` | Lock file path (default: `translation-lock.json`) |
+| `--api-key <key>` | OpenRouter API key (or set `OPENROUTER_API_KEY`) |
+| `--model <model>` | AI model to use (default: `google/gemini-2.5-flash`) |
+
+Example with custom options:
+
+```bash
+bun x i18n-ai sync --locales es,fr,de --model anthropic/claude-3-haiku
+```
+
+### Environment Variables
+
+You need to provide an API key for the AI provider.
+
+Create a `.env` file:
+
+```env
+OPENROUTER_API_KEY=your_api_key
+```
+
+### Automate with GitHub Actions
+
+You can automate translations whenever you push changes to your default locale.
+
+Create `.github/workflows/i18n-translate.yml`:
+
+```yaml
+name: AI Translation Sync
+
+on:
+  push:
+    paths:
+      - 'public/messages/en.json' # Monitor ONLY source locale
+
+jobs:
+  translate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+       - run: bun install
+       - run: bun x i18n-ai sync --api-key ${{ secrets.OPENROUTER_API_KEY }}
+      - run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          if [[ -n $(git status -s) ]]; then
+            git add public/messages/*.json translation-lock.json
+            git commit -m "chore(i18n): update translations [skip ci]"
+            git push
+          fi
+```
+
+## Programmatic Usage
+
+You can also use the library programmatically:
+
+```typescript
+import { TranslationService } from '@ccgp/i18n-ai';
+import { resolve } from 'path';
+
+const service = new TranslationService({
+  locales: ['en', 'es', 'fr'],
+  defaultLocale: 'en',
+  messagesDir: resolve(process.cwd(), 'messages'),
+  lockFilePath: resolve(process.cwd(), 'translation-lock.json'),
+  apiKey: process.env.OPENROUTER_API_KEY
+});
+
+await service.sync();
+```
+
+## License
+
+ISC

package/dist/chunk-IOH4K3A3.mjs

@@ -0,0 +1,286 @@
+// src/core/lock.ts
+import { createHash } from "crypto";
+import { readFile, writeFile } from "fs/promises";
+import { lock as acquireLock } from "proper-lockfile";
+var hash = (text) => createHash("sha256").update(text).digest("hex").slice(0, 32);
+var hashesMatch = (current, stored) => current === stored || stored.length === 16 && current.startsWith(stored);
+async function loadLock(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf-8"));
+  } catch (e) {
+    if (e.code === "ENOENT") return { locales: {} };
+    if (e instanceof SyntaxError)
+      throw new Error(`Lock file corrupted: ${path}`);
+    throw e;
+  }
+}
+async function saveLock(path, lock) {
+  await writeFile(path, `${JSON.stringify(lock, null, 2)}
+`);
+}
+async function withLockFile(path, fn) {
+  let lock = await loadLock(path);
+  if (Object.keys(lock.locales).length === 0) await saveLock(path, lock);
+  const release = await acquireLock(path, {
+    retries: { retries: 5, factor: 2, minTimeout: 1e3, maxTimeout: 5e3 },
+    stale: 3e4
+  });
+  try {
+    lock = await loadLock(path);
+    const result = await fn(lock);
+    await saveLock(path, lock);
+    return result;
+  } finally {
+    await release();
+  }
+}
+function analyzeLocale(base, target, locale, lock) {
+  const result = {
+    locale,
+    toTranslate: [],
+    toPreserve: /* @__PURE__ */ new Map(),
+    toRemove: /* @__PURE__ */ new Set(),
+    manualEdits: /* @__PURE__ */ new Map()
+  };
+  const localeData = lock.locales[locale] ?? {};
+  for (const [key, text] of base) {
+    const entry = localeData[key];
+    const current = target.get(key);
+    const currentHash = hash(text);
+    if (!entry) {
+      current ? result.toPreserve.set(key, current) : result.toTranslate.push({ key, text, status: "new" });
+    } else if (!hashesMatch(currentHash, entry.sourceHash)) {
+      result.toTranslate.push({ key, text, status: "modified" });
+    } else if (current && current !== entry.translation) {
+      result.manualEdits.set(key, current);
+    } else {
+      result.toPreserve.set(key, current ?? entry.translation);
+    }
+  }
+  for (const key of target.keys()) {
+    if (!base.has(key)) result.toRemove.add(key);
+  }
+  return result;
+}
+function updateLock(lock, locale, base, final) {
+  lock.locales[locale] ??= {};
+  const localeData = lock.locales[locale];
+  for (const [key, translation] of final) {
+    const sourceText = base.get(key);
+    if (sourceText) {
+      localeData[key] = {
+        sourceHash: hash(sourceText),
+        sourceText,
+        translation
+      };
+    }
+  }
+  for (const key of Object.keys(localeData)) {
+    if (!base.has(key)) delete localeData[key];
+  }
+}
+
+// src/core/translator.ts
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import { generateText, Output } from "ai";
+import * as z2 from "zod";
+
+// src/env.ts
+import { createEnv } from "@t3-oss/env-core";
+import * as z from "zod";
+var env = createEnv({
+  server: {
+    OPENROUTER_API_KEY: z.string()
+  },
+  runtimeEnv: process.env
+});
+
+// src/core/translator.ts
+var DEFAULT_MODEL = "google/gemini-2.5-flash";
+var translationSchema = z2.object({
+  translations: z2.array(
+    z2.object({
+      key: z2.string(),
+      value: z2.string()
+    })
+  )
+});
+var openrouter = null;
+var getOpenRouter = () => openrouter ?? (openrouter = createOpenRouter({ apiKey: env.OPENROUTER_API_KEY }));
+var SYSTEM_PROMPT = `You are a professional translator.
+
+RULES:
+1. Translate the provided key-value pairs from the source language to the target language
+2. Return an array of translations with the EXACT same keys and their translated values
+3. Do NOT translate variables in curly braces: {name}, {count}, etc. Keep them exactly as-is
+4. Maintain original tone and context
+5. For single words or short phrases, translate directly`;
+async function withRetry(fn, maxAttempts = 3) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      const msg = error.message?.toLowerCase() ?? "";
+      const retryable = msg.includes("network") || msg.includes("timeout") || msg.includes("econnreset") || msg.includes("429") || msg.includes("503") || msg.includes("502");
+      if (attempt === maxAttempts || !retryable) throw error;
+      await new Promise((r) => setTimeout(r, 2 ** (attempt - 1) * 1e3));
+    }
+  }
+  throw new Error("Unreachable");
+}
+async function translateBatch(batch) {
+  if (batch.entries.length === 0) return /* @__PURE__ */ new Map();
+  const inputArray = batch.entries.map((e) => ({ key: e.key, text: e.text }));
+  return withRetry(async () => {
+    const { output } = await generateText({
+      model: getOpenRouter().languageModel(DEFAULT_MODEL),
+      output: Output.object({
+        schema: translationSchema
+      }),
+      system: SYSTEM_PROMPT,
+      prompt: `Translate from "${batch.sourceLang}" to "${batch.targetLang}":
+
+${JSON.stringify(inputArray, null, 2)}
+
+Return the translations array with the same keys and translated values.`
+    });
+    if (!output.translations || output.translations.length === 0) {
+      throw new Error("Translation returned empty result");
+    }
+    const resultMap = new Map(output.translations.map((t) => [t.key, t.value]));
+    const missingKeys = batch.entries.filter((e) => !resultMap.has(e.key));
+    if (missingKeys.length > 0) {
+      throw new Error(
+        `Missing translations for keys: ${missingKeys.map((e) => e.key).join(", ")}`
+      );
+    }
+    return resultMap;
+  });
+}
+
+// src/core/sync.ts
+import { readFile as readFile2, writeFile as writeFile2, rename } from "fs/promises";
+import { join } from "path";
+import PQueue from "p-queue";
+var chunk = (arr, n) => Array.from(
+  { length: Math.ceil(arr.length / n) },
+  (_, i) => arr.slice(i * n, (i + 1) * n)
+);
+var flatten = (obj, prefix = "") => {
+  const result = /* @__PURE__ */ new Map();
+  for (const [k, v] of Object.entries(obj)) {
+    const path = prefix ? `${prefix}.${k}` : k;
+    typeof v === "string" ? result.set(path, v) : flatten(v, path).forEach((val, p) => result.set(p, val));
+  }
+  return result;
+};
+var unflatten = (flat) => {
+  const result = {};
+  for (const [path, value] of flat) {
+    const keys = path.split(".");
+    let cur = result;
+    for (let i = 0; i < keys.length - 1; i++) {
+      cur = cur[keys[i]] ??= {};
+    }
+    cur[keys.at(-1)] = value;
+  }
+  return result;
+};
+var readJson = async (path) => {
+  try {
+    return JSON.parse(await readFile2(path, "utf-8"));
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+};
+var writeJsonAtomic = async (path, data) => {
+  const tmp = `${path}.tmp`;
+  await writeFile2(tmp, `${JSON.stringify(data, null, 2)}
+`);
+  await rename(tmp, path);
+};
+var TranslationService = class {
+  constructor(config) {
+    this.config = config;
+    this.queue = new PQueue({ concurrency: config.concurrency ?? 10 });
+    this.batchSize = config.batchSize ?? 20;
+  }
+  queue;
+  batchSize;
+  async sync() {
+    const basePath = join(
+      this.config.messagesDir,
+      `${this.config.defaultLocale}.json`
+    );
+    const baseObj = await readJson(basePath);
+    if (!baseObj) throw new Error(`Base locale file not found: ${basePath}`);
+    const base = flatten(baseObj);
+    console.log(
+      `[ok] Loaded ${this.config.defaultLocale}.json (${base.size} keys)`
+    );
+    await withLockFile(this.config.lockFilePath, async (lock) => {
+      const locales = this.config.locales.filter(
+        (l) => l !== this.config.defaultLocale
+      );
+      await Promise.all(
+        locales.map((locale) => this.syncLocale(locale, base, lock))
+      );
+    });
+    console.log("\n[done] Synchronization complete!");
+  }
+  async syncLocale(locale, base, lock) {
+    const targetPath = join(this.config.messagesDir, `${locale}.json`);
+    const targetObj = await readJson(targetPath) ?? {};
+    const target = flatten(targetObj);
+    const changes = analyzeLocale(base, target, locale, lock);
+    const hasWork = changes.toTranslate.length > 0 || changes.toRemove.size > 0 || changes.manualEdits.size > 0;
+    console.log(
+      `
+[${locale}] ${changes.toTranslate.length} to translate, ${changes.toRemove.size} obsolete`
+    );
+    if (!hasWork) {
+      console.log("  [ok] Already synchronized");
+      return;
+    }
+    const translations = await this.translateAll(changes);
+    const final = new Map([
+      ...changes.toPreserve,
+      ...changes.manualEdits,
+      ...translations
+    ]);
+    changes.toRemove.forEach((k) => final.delete(k));
+    updateLock(lock, locale, base, final);
+    await writeJsonAtomic(targetPath, unflatten(final));
+    console.log(`  [ok] Updated ${targetPath}`);
+  }
+  async translateAll(changes) {
+    if (changes.toTranslate.length === 0) return /* @__PURE__ */ new Map();
+    const batches = chunk(changes.toTranslate, this.batchSize);
+    const results = await Promise.all(
+      batches.map(
+        (batch) => this.queue.add(
+          () => translateBatch({
+            entries: batch,
+            sourceLang: this.config.defaultLocale,
+            targetLang: changes.locale,
+            apiKey: this.config.apiKey,
+            model: this.config.model
+          })
+        )
+      )
+    );
+    return results.reduce(
+      (acc, r) => r ? new Map([...acc, ...r]) : acc,
+      /* @__PURE__ */ new Map()
+    );
+  }
+};
+
+export {
+  withLockFile,
+  analyzeLocale,
+  updateLock,
+  translateBatch,
+  TranslationService
+};

package/dist/cli.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node