nativtongue-cli 0.0.1

package/README.md

@@ -0,0 +1,98 @@
+# nativtongue-cli
+
+Dev tooling for [nativtongue](../nativtongue) — extracts translation keys from your source code, generates translation files, and auto-translates via Claude.
+
+## Install
+
+```bash
+npm install -D nativtongue-cli
+```
+
+Requires [Claude Code](https://claude.ai/code) installed and authenticated for auto-translation.
+
+## Quick start
+
+```bash
+npx nativtongue init fr es de
+```
+
+This:
+- Creates `.nativtonguerc.json` with your locales
+- Patches `vite.config.ts` to add the `tongueSync()` plugin
+- Creates the `public/i18n/` directory
+- Adds `.nativtongue/` to `.gitignore`
+
+Then start your dev server. Translations sync automatically as you write code.
+
+## Commands
+
+### `nativtongue init <locales...>`
+
+Set up nativtongue in your project.
+
+```bash
+nativtongue init fr           # French only
+nativtongue init fr es de ja  # Multiple locales
+```
+
+### `nativtongue sync`
+
+Extract keys from source files and update translation files.
+
+```bash
+nativtongue sync                    # Extract keys, add empty values for new ones
+nativtongue sync --translate        # Extract + auto-translate missing keys via Claude
+nativtongue sync --prune            # Remove stale keys no longer in source
+nativtongue sync --translate --prune  # Both
+```
+
+## Vite plugin
+
+The `tongueSync()` plugin watches your source files during development and automatically extracts keys + translates on save.
+
+```ts
+// vite.config.ts
+import { tongueSync } from 'nativtongue-cli/sync'
+
+export default defineConfig({
+  plugins: [tongueSync()],
+})
+```
+
+### How it works
+
+1. On dev server start, scans all source files and extracts translation keys
+2. On file save, re-extracts keys from the changed file (5s debounce)
+3. Diffs against the last known key set — if nothing changed, does nothing
+4. Translates new keys via `claude -p` (parallel across locales)
+5. Writes updated locale files (e.g. `public/i18n/fr.json`)
+
+### Options
+
+```ts
+tongueSync({
+  srcDir: './src',           // default: from .nativtonguerc.json or './src'
+  i18nDir: './public/i18n',  // default: from .nativtonguerc.json or './public/i18n'
+  locales: ['fr', 'es'],     // default: from .nativtonguerc.json
+})
+```
+
+## What gets extracted
+
+The static extractor finds:
+- Plain text inside JSX elements (`<p>Hello</p>`, `<h1>Welcome</h1>`)
+- `t("...")` calls from the `useT()` hook
+- Translatable attributes (`aria-label`, `placeholder`, `title`, `alt`)
+- Scoped keys inside `<TranslationScope>` (e.g. `navigation::Back`)
+
+## Configuration
+
+`.nativtonguerc.json` in your project root:
+
+```json
+{
+  "srcDir": "./src",
+  "i18nDir": "./public/i18n",
+  "locales": ["fr", "es", "de"]
+}
+```

package/dist/chunk-QQ3TF54X.js

@@ -0,0 +1,214 @@
+// src/extractor.ts
+import fs from "fs";
+var T_FUNCTION_RE = /\bt\(\s*["']([^"']+)["']\s*\)/g;
+var JSX_TEXT_RE = /<(h[1-6]|p|span|div|li|td|th|label|a|strong|em)(?:\s[^>]*)?>([^<{]+?)<\/\1>/gs;
+var ATTR_RE = /(?:aria-label|placeholder|title|alt)=["']([^"']+)["']/g;
+var SCOPE_RE = /<TranslationScope\s+context=["']([^"']+)["']\s*>/g;
+var SCOPE_CLOSE_RE = /<\/TranslationScope>/g;
+function isTranslatableText(text) {
+  if (!text || text.length < 2) return false;
+  if (text.includes("${")) return false;
+  if (/^[\d\s.,!?;:'"()-]+$/.test(text)) return false;
+  return true;
+}
+function extractKeysFromSource(source) {
+  const keys = /* @__PURE__ */ new Set();
+  const events = [];
+  for (const match of source.matchAll(SCOPE_RE)) {
+    events.push({ pos: match.index, type: "open", scope: match[1] });
+  }
+  for (const match of source.matchAll(SCOPE_CLOSE_RE)) {
+    events.push({ pos: match.index, type: "close" });
+  }
+  events.sort((a, b) => a.pos - b.pos);
+  const scopeStack = [];
+  const regions = [];
+  for (const event of events) {
+    if (event.type === "open") {
+      scopeStack.push({ pos: event.pos, scope: event.scope });
+    } else if (scopeStack.length > 0) {
+      const open = scopeStack.pop();
+      regions.push({ scope: open.scope, start: open.pos, end: event.pos });
+    }
+  }
+  function isInScope(pos) {
+    return regions.some((r) => pos >= r.start && pos < r.end);
+  }
+  for (const match of source.matchAll(T_FUNCTION_RE)) {
+    if (!isInScope(match.index)) keys.add(match[1]);
+  }
+  for (const match of source.matchAll(JSX_TEXT_RE)) {
+    if (!isInScope(match.index)) {
+      const text = match[2].trim();
+      if (isTranslatableText(text)) keys.add(text);
+    }
+  }
+  for (const match of source.matchAll(ATTR_RE)) {
+    if (!isInScope(match.index)) {
+      const text = match[1].trim();
+      if (isTranslatableText(text)) keys.add(text);
+    }
+  }
+  for (const { scope, start, end } of regions) {
+    const region = source.slice(start, end);
+    for (const match of region.matchAll(T_FUNCTION_RE)) {
+      keys.add(`${scope}::${match[1]}`);
+    }
+    for (const match of region.matchAll(JSX_TEXT_RE)) {
+      const text = match[2].trim();
+      if (isTranslatableText(text)) {
+        keys.add(`${scope}::${text}`);
+      }
+    }
+    for (const match of region.matchAll(ATTR_RE)) {
+      const text = match[1].trim();
+      if (isTranslatableText(text)) {
+        keys.add(`${scope}::${text}`);
+      }
+    }
+  }
+  return Array.from(keys);
+}
+function extractKeysFromFile(filePath) {
+  const source = fs.readFileSync(filePath, "utf-8");
+  return extractKeysFromSource(source);
+}
+
+// src/sync-locale.ts
+import fs2 from "fs";
+import path from "path";
+async function syncLocaleFile(options) {
+  const { locale, i18nDir, allKeys, provider, prune = false, retranslateEmpty = false, signal } = options;
+  const localePath = path.join(i18nDir, `${locale}.json`);
+  let existing = {};
+  if (fs2.existsSync(localePath)) {
+    const raw = JSON.parse(fs2.readFileSync(localePath, "utf-8"));
+    delete raw._disclaimer;
+    existing = raw;
+  }
+  const allKeysSet = new Set(allKeys);
+  const missingKeys = retranslateEmpty ? allKeys.filter((k) => !(k in existing) || !existing[k]) : allKeys.filter((k) => !(k in existing));
+  const staleKeys = Object.keys(existing).filter((k) => !allKeysSet.has(k));
+  let newTranslations = {};
+  if (provider && missingKeys.length > 0) {
+    console.log(`[nativtongue] Translating ${missingKeys.length} keys to ${locale}...`);
+    try {
+      newTranslations = await provider.translate(missingKeys, locale, signal);
+    } catch (err) {
+      if (err?.name === "AbortError") throw err;
+      console.warn(`[nativtongue] Translation failed for ${locale}:`, err?.message ?? err);
+      for (const k of missingKeys) newTranslations[k] = "";
+    }
+  } else {
+    for (const k of missingKeys) newTranslations[k] = "";
+  }
+  if (signal?.aborted) return;
+  const merged = {};
+  for (const key of allKeys) {
+    if (key in existing && existing[key]) {
+      merged[key] = existing[key];
+    } else if (key in newTranslations) {
+      merged[key] = newTranslations[key];
+    } else {
+      merged[key] = "";
+    }
+  }
+  if (!prune) {
+    for (const key of staleKeys) merged[key] = existing[key];
+  }
+  const output = {
+    _disclaimer: "Translations generated by Claude. Review before shipping to production.",
+    ...merged
+  };
+  fs2.writeFileSync(localePath, JSON.stringify(output, null, 2) + "\n");
+  const staleMsg = staleKeys.length > 0 ? prune ? `, ${staleKeys.length} removed (${staleKeys.join(", ")})` : `, ${staleKeys.length} stale (kept: ${staleKeys.join(", ")}). Run with --prune to remove.` : "";
+  console.log(`[nativtongue] ${locale}.json \u2014 ${missingKeys.length} added${staleMsg}`);
+}
+
+// src/locale-names.ts
+var LOCALE_NAMES = {
+  fr: "French",
+  es: "Spanish",
+  de: "German",
+  it: "Italian",
+  pt: "Portuguese",
+  ja: "Japanese",
+  ko: "Korean",
+  zh: "Chinese",
+  ar: "Arabic",
+  ru: "Russian",
+  nl: "Dutch",
+  sv: "Swedish",
+  da: "Danish",
+  no: "Norwegian",
+  fi: "Finnish",
+  pl: "Polish",
+  cs: "Czech",
+  tr: "Turkish",
+  th: "Thai",
+  vi: "Vietnamese",
+  hi: "Hindi",
+  he: "Hebrew",
+  uk: "Ukrainian",
+  ro: "Romanian",
+  hu: "Hungarian"
+};
+var LOCALE_RE = /^[a-z]{2,3}(-[A-Z]{2,3})?$/;
+function localeName(code) {
+  return LOCALE_NAMES[code] ?? code;
+}
+function isValidLocale(locale) {
+  return LOCALE_RE.test(locale);
+}
+function parseJsonResponse(raw) {
+  let cleaned = raw.trim();
+  if (cleaned.startsWith("```"))
+    cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, "").replace(/\n?```\s*$/, "");
+  return JSON.parse(cleaned);
+}
+
+// src/translate-provider.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function buildPrompt(batch, targetLocale) {
+  return `Translate the following UI strings to ${localeName(targetLocale)} (${targetLocale}). Return ONLY a JSON object mapping each original string to its translation. No markdown, no explanation, no wrapping.
+
+Some keys use "scope::text" format (e.g. "navigation::Back"). The scope is context, not text to translate. Translate only the part after "::" but keep the full key in the output. For example, "navigation::Back" should be translated based on the word "Back" in a navigation context.
+
+Strings to translate:
+${JSON.stringify(batch, null, 2)}`;
+}
+var BATCH_SIZE = 50;
+function createClaudeCliProvider() {
+  return {
+    async translate(keys, targetLocale, signal) {
+      const result = {};
+      for (let i = 0; i < keys.length; i += BATCH_SIZE) {
+        const batch = keys.slice(i, i + BATCH_SIZE);
+        const prompt = buildPrompt(batch, targetLocale);
+        try {
+          const { stdout } = await execFileAsync("claude", ["-p", prompt], {
+            maxBuffer: 10 * 1024 * 1024,
+            signal
+          });
+          const parsed = parseJsonResponse(stdout);
+          Object.assign(result, parsed);
+        } catch (err) {
+          if (err?.name === "AbortError") throw err;
+          console.warn(`[nativtongue] Claude CLI failed for batch ${i / BATCH_SIZE + 1}:`, err);
+          for (const k of batch) result[k] = "";
+        }
+      }
+      return result;
+    }
+  };
+}
+
+export {
+  extractKeysFromSource,
+  extractKeysFromFile,
+  syncLocaleFile,
+  isValidLocale,
+  createClaudeCliProvider
+};

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import {
+  createClaudeCliProvider,
+  extractKeysFromFile,
+  isValidLocale,
+  syncLocaleFile
+} from "./chunk-QQ3TF54X.js";
+
+// src/cli.ts
+import fs3 from "fs";
+import path2 from "path";
+
+// src/sync.ts
+import fs from "fs";
+import { glob } from "glob";
+async function sync(options) {
+  const { srcDir, i18nDir, locales, provider, prune = false } = options;
+  const files = await glob("**/*.{tsx,jsx,ts,js}", {
+    cwd: srcDir,
+    absolute: true,
+    ignore: ["**/node_modules/**", "**/dist/**"]
+  });
+  const staticKeys = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const keys = extractKeysFromFile(file);
+    keys.forEach((k) => staticKeys.add(k));
+  }
+  console.log(`[nativtongue] Found ${staticKeys.size} keys from static analysis`);
+  const allKeys = Array.from(staticKeys).sort();
+  fs.mkdirSync(i18nDir, { recursive: true });
+  await Promise.allSettled(
+    locales.map(
+      (locale) => syncLocaleFile({ locale, i18nDir, allKeys, provider, prune })
+    )
+  );
+}
+
+// src/init.ts
+import fs2 from "fs";
+import path from "path";
+var VITE_CONFIG_NAMES = [
+  "vite.config.ts",
+  "vite.config.js",
+  "vite.config.mts",
+  "vite.config.mjs"
+];
+function init(locales) {
+  const cwd = process.cwd();
+  if (locales.length === 0) {
+    console.error("[nativtongue] Specify at least one locale: nativtongue init fr es de");
+    process.exit(1);
+  }
+  const rcPath = path.join(cwd, ".nativtonguerc.json");
+  if (fs2.existsSync(rcPath)) {
+    console.log("[nativtongue] .nativtonguerc.json already exists, skipping");
+  } else {
+    const rc = { srcDir: "./src", i18nDir: "./public/i18n", locales };
+    fs2.writeFileSync(rcPath, JSON.stringify(rc, null, 2) + "\n");
+    console.log("[nativtongue] Created .nativtonguerc.json");
+  }
+  const i18nDir = path.join(cwd, "public/i18n");
+  fs2.mkdirSync(i18nDir, { recursive: true });
+  const viteConfig = VITE_CONFIG_NAMES.map((name) => path.join(cwd, name)).find((p) => fs2.existsSync(p));
+  if (viteConfig) {
+    let source = fs2.readFileSync(viteConfig, "utf-8");
+    if (source.includes("tongueSync")) {
+      console.log("[nativtongue] Vite config already has tongueSync plugin, skipping");
+    } else {
+      const importLine = "import { tongueSync } from 'nativtongue-cli/sync'\n";
+      const lastImportIdx = source.lastIndexOf("\nimport ");
+      if (lastImportIdx !== -1) {
+        const lineEnd = source.indexOf("\n", lastImportIdx + 1);
+        source = source.slice(0, lineEnd + 1) + importLine + source.slice(lineEnd + 1);
+      } else {
+        source = importLine + source;
+      }
+      const pluginsMatch = source.match(/plugins\s*:\s*\[/);
+      if (pluginsMatch && pluginsMatch.index !== void 0) {
+        const insertAt = pluginsMatch.index + pluginsMatch[0].length;
+        source = source.slice(0, insertAt) + "\n    tongueSync()," + source.slice(insertAt);
+      } else {
+        console.warn("[nativtongue] Could not find plugins array in vite config \u2014 add tongueSync() manually");
+      }
+      fs2.writeFileSync(viteConfig, source);
+      console.log(`[nativtongue] Patched ${path.basename(viteConfig)}`);
+    }
+  } else {
+    console.warn("[nativtongue] No vite.config found \u2014 add tongueSync() plugin manually");
+  }
+  const gitignorePath = path.join(cwd, ".gitignore");
+  if (fs2.existsSync(gitignorePath)) {
+    const gitignore = fs2.readFileSync(gitignorePath, "utf-8");
+    if (!gitignore.includes(".nativtongue")) {
+      fs2.appendFileSync(gitignorePath, "\n# nativtongue\n.nativtongue/\n");
+      console.log("[nativtongue] Added .nativtongue/ to .gitignore");
+    }
+  } else {
+    fs2.writeFileSync(gitignorePath, "# nativtongue\n.nativtongue/\n");
+    console.log("[nativtongue] Created .gitignore");
+  }
+  console.log(`
+Done! Next steps:
+  1. Wrap your root component:
+
+     import { TranslationProvider } from 'nativtongue'
+
+     <TranslationProvider defaultLocale="en">
+       <App />
+     </TranslationProvider>
+
+  2. Start your dev server \u2014 translations sync automatically.
+`);
+}
+
+// src/cli.ts
+function loadConfig() {
+  const configPath = path2.resolve(process.cwd(), ".nativtonguerc.json");
+  if (!fs3.existsSync(configPath)) return {};
+  try {
+    return JSON.parse(fs3.readFileSync(configPath, "utf-8"));
+  } catch {
+    console.error(`[nativtongue] Invalid JSON in ${configPath}`);
+    process.exit(1);
+  }
+}
+async function main() {
+  const command = process.argv[2];
+  if (!command || command === "help" || command === "--help") {
+    console.log(`
+nativtongue \u2014 translation sync CLI
+
+Commands:
+  init <locales...>    Set up nativtongue in your project
+                       Example: nativtongue init fr es de
+
+  sync [options]       Extract keys and update translation files
+    --translate        Auto-fill missing translations
+    --prune            Remove stale keys from translation files
+
+Translation uses your local Claude Code installation (no API key needed).
+`);
+    return;
+  }
+  if (command === "init") {
+    const locales = process.argv.slice(3).filter((a) => !a.startsWith("-"));
+    init(locales);
+    return;
+  }
+  if (command === "sync") {
+    const config = loadConfig();
+    const shouldTranslate = process.argv.includes("--translate");
+    const shouldPrune = process.argv.includes("--prune");
+    const srcDir = path2.resolve(process.cwd(), config.srcDir ?? "./src");
+    const i18nDir = path2.resolve(process.cwd(), config.i18nDir ?? "./public/i18n");
+    const rawLocales = config.locales ?? [];
+    const invalid = rawLocales.filter((l) => !isValidLocale(l));
+    if (invalid.length > 0) {
+      console.error(`[nativtongue] Invalid locale codes: ${invalid.join(", ")}`);
+      process.exit(1);
+    }
+    const locales = rawLocales;
+    if (locales.length === 0) {
+      console.error('[nativtongue] No locales configured. Add "locales" to .nativtonguerc.json');
+      process.exit(1);
+    }
+    let provider = void 0;
+    if (shouldTranslate) {
+      provider = createClaudeCliProvider();
+    }
+    await sync({ srcDir, i18nDir, locales, provider, prune: shouldPrune });
+  } else {
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+  }
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/tongue-sync.d.ts

@@ -0,0 +1,10 @@
+import { Plugin } from 'vite';
+
+interface TongueSyncOptions {
+    srcDir?: string;
+    i18nDir?: string;
+    locales?: string[];
+}
+declare function tongueSync(options?: TongueSyncOptions): Plugin;
+
+export { type TongueSyncOptions, tongueSync };

package/dist/tongue-sync.js

@@ -0,0 +1,120 @@
+import {
+  createClaudeCliProvider,
+  extractKeysFromSource,
+  isValidLocale,
+  syncLocaleFile
+} from "./chunk-QQ3TF54X.js";
+
+// src/tongue-sync.ts
+import fs from "fs";
+import path from "path";
+import { glob } from "glob";
+function tongueSync(options) {
+  const keyCache = /* @__PURE__ */ new Map();
+  let lastSyncedSnapshot = "";
+  let debounceTimer = null;
+  let inFlightAbort = null;
+  let syncing = false;
+  let srcDir;
+  let i18nDir;
+  let locales;
+  const provider = createClaudeCliProvider();
+  function loadRcConfig() {
+    const rcPath = path.resolve(process.cwd(), ".nativtonguerc.json");
+    if (fs.existsSync(rcPath)) {
+      try {
+        return JSON.parse(fs.readFileSync(rcPath, "utf-8"));
+      } catch {
+      }
+    }
+    return {};
+  }
+  function getAllKeys() {
+    const all = /* @__PURE__ */ new Set();
+    for (const keys of keyCache.values()) keys.forEach((k) => all.add(k));
+    return Array.from(all).sort();
+  }
+  function updateFileCache(filePath) {
+    try {
+      const source = fs.readFileSync(filePath, "utf-8");
+      keyCache.set(filePath, extractKeysFromSource(source));
+    } catch {
+      keyCache.delete(filePath);
+    }
+  }
+  async function initialScan() {
+    const files = await glob("**/*.{tsx,jsx,ts,js}", {
+      cwd: srcDir,
+      absolute: true,
+      ignore: ["**/node_modules/**", "**/dist/**"]
+    });
+    for (const file of files) updateFileCache(file);
+  }
+  function scheduleSync() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => runSync(), 5e3);
+  }
+  async function runSync() {
+    if (locales.length === 0) return;
+    const allKeys = getAllKeys();
+    const snapshot = JSON.stringify(allKeys);
+    if (snapshot === lastSyncedSnapshot) return;
+    lastSyncedSnapshot = snapshot;
+    if (inFlightAbort) {
+      inFlightAbort.abort();
+      inFlightAbort = null;
+    }
+    syncing = true;
+    const abort = new AbortController();
+    inFlightAbort = abort;
+    try {
+      fs.mkdirSync(i18nDir, { recursive: true });
+      await Promise.allSettled(
+        locales.map(
+          (locale) => syncLocaleFile({
+            locale,
+            i18nDir,
+            allKeys,
+            provider,
+            prune: true,
+            retranslateEmpty: true,
+            signal: abort.signal
+          })
+        )
+      );
+    } finally {
+      syncing = false;
+      inFlightAbort = null;
+    }
+  }
+  return {
+    name: "nativtongue",
+    configResolved() {
+      const rc = loadRcConfig();
+      srcDir = path.resolve(process.cwd(), options?.srcDir ?? rc.srcDir ?? "./src");
+      i18nDir = path.resolve(process.cwd(), options?.i18nDir ?? rc.i18nDir ?? "./public/i18n");
+      const rawLocales = options?.locales ?? rc.locales ?? [];
+      const invalid = rawLocales.filter((l) => !isValidLocale(l));
+      if (invalid.length > 0) {
+        console.warn(`[nativtongue] Invalid locale codes ignored: ${invalid.join(", ")}`);
+      }
+      locales = rawLocales.filter((l) => isValidLocale(l));
+    },
+    configureServer() {
+      initialScan().then(() => {
+        if (locales.length > 0) runSync();
+      });
+    },
+    handleHotUpdate({ file }) {
+      if (!file.startsWith(srcDir)) return;
+      if (!file.match(/\.(tsx?|jsx?)$/)) return;
+      if (file.startsWith(i18nDir)) return;
+      if (syncing) return;
+      updateFileCache(file);
+      scheduleSync();
+    }
+  };
+}
+export {
+  tongueSync
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "nativtongue-cli",
+  "version": "0.0.1",
+  "description": "CLI and dev tooling for nativtongue — extract, sync, and translate",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "exports": {
+    ".": "./dist/cli.js",
+    "./sync": {
+      "types": "./dist/tongue-sync.d.ts",
+      "import": "./dist/tongue-sync.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "nativtongue": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsup src/cli.ts src/tongue-sync.ts --format esm --dts --external vite",
+    "dev": "tsup src/cli.ts src/tongue-sync.ts --format esm --dts --external vite --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "glob": "^11.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.8",
+    "vitest": "^4.1.4"
+  },
+  "packageManager": "pnpm@10.33.0"
+}