@wbcom/i18n-ai 0.1.0

package/.wbcom-i18n.example.json

@@ -0,0 +1,21 @@
+{
+  "domain": "jetonomy",
+  "potFile": "languages/jetonomy.pot",
+  "languagesDir": "languages",
+  "engine": "claude",
+  "model": "haiku",
+  "batch": 40,
+  "makeJson": true,
+  "protect": ["Jetonomy", "Pro", "WordPress", "BuddyPress", "REST", "API", "URL", "CSV", "AI"],
+  "glossary": {
+    "Space": "",
+    "Trust Level": ""
+  },
+  "locales": [
+    { "locale": "de_DE", "name": "German",  "register": "informal (du)" },
+    { "locale": "fr_FR", "name": "French",  "register": "informal (tu)" },
+    { "locale": "es_ES", "name": "Spanish", "register": "informal (tú)" },
+    { "locale": "nl_NL", "name": "Dutch",   "register": "informal (je)" },
+    { "locale": "ko_KR", "name": "Korean",  "register": "polite (해요체)", "model": "sonnet" }
+  ]
+}

package/README.md

@@ -0,0 +1,55 @@
+# @wbcom/i18n-ai
+
+AI-translate WordPress plugin/theme `.po` files as part of your build/release — **sync new strings, translate them, validate, compile**. Wires into `grunt` and `bin/build-release.sh`; reusable across every plugin via one `devDependency`.
+
+It does **not** replace human translators where you want them — it produces solid first-pass translations (Claude) so locales ship populated; site owners refine per-site with **Loco Translate**.
+
+## How it works
+
+```
+grunt makepot                 # your existing step → fresh .pot
+wbcom-i18n sync               # msgmerge .pot → each locale .po  (NEW → untranslated, CHANGED → fuzzy)
+wbcom-i18n translate          # AI-fill ONLY untranslated + fuzzy entries (incremental, cheap)
+wbcom-i18n compile            # msgfmt -c → .mo  +  wp i18n make-json → JS/block .json
+# or: wbcom-i18n all
+```
+
+- **Incremental** — `sync` (msgmerge) means each release only translates *new/changed* strings; existing translations are preserved.
+- **Crash-safe** — every translation's printf placeholders (`%s`, `%1$s`…) are validated against the source. A mismatch marks the entry `fuzzy`, so gettext won't compile it → the string **falls back to English instead of crashing**. No human review required for safety.
+- **Brand-aware** — `protect` terms (Jetonomy, Pro, WordPress…) and an optional `glossary` keep terminology consistent.
+
+## Install
+
+```bash
+npm i -D @wbcom/i18n-ai          # plus system tools: gettext (msginit/msgmerge/msgfmt), wp-cli, and the `claude` CLI
+```
+
+Requirements: Node ≥18, GNU **gettext**, **wp-cli** (for `make-json`), and an engine — the **`claude` CLI** (default, no API key) or `ANTHROPIC_API_KEY` (`--engine=api`).
+
+## Configure — `.wbcom-i18n.json` (plugin root)
+
+See `.wbcom-i18n.example.json`. Per-locale `model` lets you use Haiku for European languages and Sonnet for Korean/CJK.
+
+## CLI
+
+```bash
+wbcom-i18n all                       # sync → translate → compile, all locales
+wbcom-i18n translate --locales=de_DE # one locale
+wbcom-i18n sync                      # just merge new strings
+wbcom-i18n compile                   # just build .mo + .json
+wbcom-i18n all --engine=api --model=sonnet
+```
+
+## Grunt
+
+```js
+// Gruntfile.js
+require('@wbcom/i18n-ai/grunt')(grunt);
+grunt.registerTask('build', ['makepot', 'i18n', 'rtlcss', 'cssmin', 'uglify']);
+```
+
+`grunt i18n` runs sync → translate → compile, so `grunt build` (and your release script) keeps all locales current automatically.
+
+## License
+
+GPL-2.0-or-later.

package/bin/wbcom-i18n.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+'use strict';
+const { loadConfig } = require('../lib/config');
+const { syncLocales } = require('../lib/sync');
+const { translatePo } = require('../lib/translate');
+const { compileLocales } = require('../lib/compile');
+
+const log = (m) => console.log(m);
+
+function parseArgs(argv) {
+  const a = { _: [] };
+  for (const t of argv) {
+    if (t.startsWith('--')) { const [k, v] = t.slice(2).split('='); a[k] = v === undefined ? true : v; }
+    else a._.push(t);
+  }
+  return a;
+}
+
+const USAGE = `wbcom-i18n <command> [options]
+  Commands: sync | translate | compile | all (default)
+  Options:
+    --config=<file>     config file (default .wbcom-i18n.json)
+    --locales=de_DE,..  only these locales
+    --engine=claude|api override engine
+    --model=haiku|...   override default model
+`;
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || args.h) { process.stdout.write(USAGE); return; }
+  const cmd = args._[0] || 'all';
+  const cfg = loadConfig(process.cwd(), typeof args.config === 'string' ? args.config : '.wbcom-i18n.json');
+  if (args.locales) { const want = String(args.locales).split(','); cfg.locales = cfg.locales.filter((l) => want.includes(l.locale)); }
+  if (typeof args.engine === 'string') cfg.engine = args.engine;
+  if (typeof args.model === 'string') cfg.model = args.model;
+  if (args.limit) cfg.limit = parseInt(String(args.limit), 10);
+  if (!cfg.locales.length) throw new Error('no locales selected');
+
+  if (cmd === 'sync' || cmd === 'all') { log('▶ sync'); syncLocales(cfg, log); }
+  if (cmd === 'translate' || cmd === 'all') {
+    log('▶ translate');
+    for (const loc of cfg.locales) await translatePo(loc.poFile, loc, cfg, log);
+  }
+  if (cmd === 'compile' || cmd === 'all') { log('▶ compile'); compileLocales(cfg, log); }
+  log('✓ done');
+}
+main().catch((e) => { console.error('ERROR:', e.message); process.exit(1); });

package/grunt/index.js

@@ -0,0 +1,18 @@
+'use strict';
+// Register a `grunt i18n` task. In your Gruntfile.js:
+//   require('@wbcom/i18n-ai/grunt')(grunt);
+//   grunt.registerTask('build', ['makepot', 'i18n', 'rtlcss', 'cssmin', 'uglify']);
+module.exports = function (grunt) {
+  const { loadConfig, syncLocales, translatePo, compileLocales } = require('../lib');
+  grunt.registerTask('i18n', 'Sync + AI-translate + compile locale .po files', function () {
+    const done = this.async();
+    (async () => {
+      const cfg = loadConfig(process.cwd());
+      const w = (m) => grunt.log.writeln(m);
+      grunt.log.subhead('i18n: sync'); syncLocales(cfg, w);
+      grunt.log.subhead('i18n: translate');
+      for (const loc of cfg.locales) await translatePo(loc.poFile, loc, cfg, w);
+      grunt.log.subhead('i18n: compile'); compileLocales(cfg, w);
+    })().then(() => done(), (e) => { grunt.log.error(e.message); done(false); });
+  });
+};

package/lib/compile.js

@@ -0,0 +1,28 @@
+'use strict';
+const { execFileSync } = require('child_process');
+
+function sh(cmd, args) {
+  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/**
+ * Compile each locale .po -> .mo (with `-c` = the crash-safety check), then emit
+ * the JSON files block/JS i18n needs (wp i18n make-json). msgfmt -c fails loudly
+ * on any format/placeholder error a fuzzy flag didn't already neutralise.
+ */
+function compileLocales(cfg, log = () => {}) {
+  for (const loc of cfg.locales) {
+    sh('msgfmt', ['-c', '-o', loc.moFile, loc.poFile]);
+    log(`  compile ${loc.locale}: ${loc.moFile}`);
+  }
+  if (cfg.makeJson) {
+    try {
+      sh('wp', ['i18n', 'make-json', cfg.languagesDir, '--no-purge', `--domain=${cfg.domain}`]);
+      log('  make-json: emitted JS/block translations');
+    } catch (e) {
+      log(`  make-json skipped (wp-cli i18n unavailable): ${String(e.message).split('\n')[0]}`);
+    }
+  }
+}
+
+module.exports = { compileLocales };

package/lib/config.js

@@ -0,0 +1,33 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = {
+  engine: 'claude',     // 'claude' (CLI, no key) | 'api' (ANTHROPIC_API_KEY)
+  model: 'haiku',
+  batch: 40,
+  languagesDir: 'languages',
+  makeJson: true,       // also emit .json for block/JS i18n
+  protect: ['Jetonomy', 'Pro', 'WordPress', 'BuddyPress', 'REST', 'API', 'URL', 'CSV', 'AI', 'HTML', 'CSS'],
+  glossary: {},
+  locales: [],
+};
+
+/** Load .wbcom-i18n.json from cwd (plugin root), merge defaults, resolve paths. */
+function loadConfig(cwd = process.cwd(), file = '.wbcom-i18n.json') {
+  const p = path.resolve(cwd, file);
+  if (!fs.existsSync(p)) throw new Error(`Config not found: ${p}`);
+  const cfg = { ...DEFAULTS, ...JSON.parse(fs.readFileSync(p, 'utf8')) };
+  cfg.cwd = cwd;
+  if (!cfg.domain) throw new Error('config.domain is required (the text domain / slug)');
+  cfg.languagesDir = path.resolve(cwd, cfg.languagesDir);
+  cfg.potFile = path.resolve(cwd, cfg.potFile || path.join('languages', `${cfg.domain}.pot`));
+  cfg.locales = cfg.locales.map((l) => ({
+    register: 'neutral', ...l,
+    poFile: path.join(cfg.languagesDir, `${cfg.domain}-${l.locale}.po`),
+    moFile: path.join(cfg.languagesDir, `${cfg.domain}-${l.locale}.mo`),
+  }));
+  return cfg;
+}
+
+module.exports = { loadConfig, DEFAULTS };

package/lib/index.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  loadConfig: require('./config').loadConfig,
+  syncLocales: require('./sync').syncLocales,
+  translatePo: require('./translate').translatePo,
+  compileLocales: require('./compile').compileLocales,
+};

package/lib/sync.js

@@ -0,0 +1,31 @@
+'use strict';
+const fs = require('fs');
+const { execFileSync } = require('child_process');
+
+function sh(cmd, args) {
+  return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+/**
+ * Bring every locale .po in lockstep with the current .pot.
+ * - missing .po  -> msginit (fresh, all untranslated)
+ * - existing .po -> msgmerge (NEW strings appear untranslated, CHANGED ones fuzzy)
+ * This is the "sync new strings" step: only new/changed entries become work for
+ * the translate step; existing translations are preserved.
+ */
+function syncLocales(cfg, log = () => {}) {
+  if (!fs.existsSync(cfg.potFile)) {
+    throw new Error(`POT not found: ${cfg.potFile} (run 'grunt makepot' / 'wp i18n make-pot' first)`);
+  }
+  for (const loc of cfg.locales) {
+    if (fs.existsSync(loc.poFile)) {
+      sh('msgmerge', ['--update', '--backup=none', '--no-fuzzy-matching', loc.poFile, cfg.potFile]);
+      log(`  sync ${loc.locale}: merged new/changed strings`);
+    } else {
+      sh('msginit', ['--no-translator', `--locale=${loc.locale}`, `--input=${cfg.potFile}`, `--output=${loc.poFile}`]);
+      log(`  sync ${loc.locale}: created ${loc.poFile}`);
+    }
+  }
+}
+
+module.exports = { syncLocales };

package/lib/translate.js

@@ -0,0 +1,103 @@
+'use strict';
+const fs = require('fs');
+const { po } = require('gettext-parser');
+const { samePlaceholders, translateBatch, npluralsOf } = require('./util');
+
+const DEFAULT_PROTECT = ['Jetonomy', 'Pro', 'WordPress', 'BuddyPress', 'REST', 'API', 'URL', 'CSV', 'AI', 'HTML', 'CSS'];
+
+function buildPrompt(cfg, loc, input) {
+  const protect = (cfg.protect || DEFAULT_PROTECT).join(', ');
+  const gloss = cfg.glossary && Object.keys(cfg.glossary).length
+    ? ` Use this glossary (English -> ${loc.name}) consistently: ${JSON.stringify(cfg.glossary)}.`
+    : '';
+  return (
+    `Translate these WordPress plugin UI strings to ${loc.name} (${loc.locale}), ${loc.register || 'neutral'} register. ` +
+    `Return ONLY a compact JSON object mapping each input key to its ${loc.name} translation - no markdown, no commentary. ` +
+    `PRESERVE EXACTLY, never translate or reorder: printf placeholders (%s, %d, %1$s, %2$d ...), HTML tags and entities, ` +
+    `and these terms: ${protect}. Keep trailing punctuation/ellipsis and any leading/trailing spaces.${gloss} ` +
+    `Input: ${JSON.stringify(input)}`
+  );
+}
+
+function flagSet(entry) {
+  return new Set((entry.comments && entry.comments.flag ? entry.comments.flag : '').split(',').map(s => s.trim()).filter(Boolean));
+}
+function setFuzzy(entry, on) {
+  const flags = flagSet(entry);
+  if (on) flags.add('fuzzy'); else flags.delete('fuzzy');
+  entry.comments = entry.comments || {};
+  entry.comments.flag = [...flags].join(', ');
+}
+function isFuzzy(entry) { return flagSet(entry).has('fuzzy'); }
+
+/** Fill one locale .po in place. Returns {total, filled, fuzzy}. */
+async function translatePo(poPath, loc, cfg, log = () => {}) {
+  const data = po.parse(fs.readFileSync(poPath));
+  const nplurals = npluralsOf(data.headers['plural-forms'] || data.headers['Plural-Forms']);
+  const model = loc.model || cfg.model || 'haiku';
+  const engine = cfg.engine || 'claude';
+  const batchSize = cfg.batch || 40;
+
+  // Collect slots needing translation: empty, or fuzzy (changed source via msgmerge).
+  const items = [];
+  const touched = new Set();
+  for (const ctx of Object.keys(data.translations)) {
+    for (const key of Object.keys(data.translations[ctx])) {
+      const e = data.translations[ctx][key];
+      if (e.msgid === '') continue; // header
+      const fuzzy = isFuzzy(e);
+      if (e.msgid_plural) {
+        if (fuzzy || !e.msgstr[0]) items.push({ e, slot: 0, src: e.msgid });
+        for (let n = 1; n < nplurals; n++) if (fuzzy || !e.msgstr[n]) items.push({ e, slot: n, src: e.msgid_plural });
+      } else if (fuzzy || !e.msgstr[0]) {
+        items.push({ e, slot: 0, src: e.msgid });
+      }
+    }
+  }
+
+  if (cfg.limit && items.length > cfg.limit) items.length = cfg.limit; // test cap
+  const total = items.length;
+  log(`${loc.locale}: ${total} strings to fill (model=${model}, engine=${engine}, nplurals=${nplurals})`);
+  let filled = 0;
+  for (let i = 0; i < total; i += batchSize) {
+    const chunk = items.slice(i, i + batchSize);
+    const input = {};
+    chunk.forEach((it, j) => { input[j] = it.src; });
+    let res;
+    try {
+      res = await translateBatch(buildPrompt(cfg, loc, input), model, engine);
+    } catch (err) {
+      log(`  ${loc.locale}: batch ${i} error: ${err.message}`);
+      continue;
+    }
+    chunk.forEach((it, j) => {
+      const t = res[j] != null ? String(res[j]) : '';
+      if (!t) return;
+      it.e.msgstr[it.slot] = t;
+      touched.add(it.e);
+      filled++;
+    });
+    log(`  ${loc.locale}: ${Math.min(i + batchSize, total)}/${total}`);
+  }
+
+  // Crash-safety validation: any msgstr whose placeholders differ from its source
+  // marks the WHOLE entry fuzzy -> gettext won't compile it -> English fallback.
+  let fuzzy = 0;
+  for (const e of touched) {
+    let bad = false;
+    if (e.msgid_plural) {
+      if (e.msgstr[0] && !samePlaceholders(e.msgid, e.msgstr[0])) bad = true;
+      for (let n = 1; n < nplurals; n++) if (e.msgstr[n] && !samePlaceholders(e.msgid_plural, e.msgstr[n])) bad = true;
+    } else if (e.msgstr[0] && !samePlaceholders(e.msgid, e.msgstr[0])) {
+      bad = true;
+    }
+    setFuzzy(e, bad);
+    if (bad) fuzzy++;
+  }
+
+  fs.writeFileSync(poPath, po.compile(data));
+  log(`DONE ${loc.locale}: filled=${filled} fuzzy(placeholder-fallback)=${fuzzy}`);
+  return { total, filled, fuzzy };
+}
+
+module.exports = { translatePo };

package/lib/util.js

@@ -0,0 +1,59 @@
+'use strict';
+const { execFileSync } = require('child_process');
+
+// printf placeholders WordPress uses: %s %d %1$s %2$d ... and literal %%
+const PH = /%%|%(?:\d+\$)?[bcdeEfFgGosuxX]/g;
+
+function placeholders(s) {
+  return ((s || '').match(PH) || []).slice().sort();
+}
+function samePlaceholders(a, b) {
+  const x = placeholders(a), y = placeholders(b);
+  return x.length === y.length && x.every((v, i) => v === y[i]);
+}
+
+// Strip markdown fences / prose and isolate the JSON object the model returned.
+function extractJson(out) {
+  let s = String(out).trim();
+  s = s.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/i, '');
+  const m = s.match(/\{[\s\S]*\}/);
+  return JSON.parse(m ? m[0] : s);
+}
+
+// Engine: claude CLI (default, no key) — model is an alias like "haiku"/"sonnet".
+function callClaude(prompt, model) {
+  const out = execFileSync('claude', ['-p', '--model', model, prompt], {
+    encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, timeout: 300000,
+  });
+  return extractJson(out);
+}
+
+// Engine: Anthropic API (needs ANTHROPIC_API_KEY). Aliases mapped to model IDs.
+const API_MODELS = {
+  haiku: 'claude-haiku-4-5-20251001',
+  sonnet: 'claude-sonnet-4-6',
+  opus: 'claude-opus-4-8',
+};
+async function callApi(prompt, model) {
+  const key = process.env.ANTHROPIC_API_KEY;
+  if (!key) throw new Error('ANTHROPIC_API_KEY not set (engine=api)');
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+    body: JSON.stringify({ model: API_MODELS[model] || model, max_tokens: 8000, messages: [{ role: 'user', content: prompt }] }),
+  });
+  const j = await res.json();
+  if (!j.content) throw new Error('API error: ' + JSON.stringify(j).slice(0, 200));
+  return extractJson(j.content[0].text);
+}
+
+function translateBatch(prompt, model, engine) {
+  return engine === 'api' ? callApi(prompt, model) : Promise.resolve(callClaude(prompt, model));
+}
+
+function npluralsOf(pluralForms) {
+  const m = /nplurals\s*=\s*(\d+)/.exec(pluralForms || '');
+  return m ? parseInt(m[1], 10) : 2;
+}
+
+module.exports = { placeholders, samePlaceholders, extractJson, translateBatch, npluralsOf };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@wbcom/i18n-ai",
+  "version": "0.1.0",
+  "description": "AI-translate WordPress plugin/theme .po files: sync new strings (msgmerge), translate (Claude), validate placeholders, compile .mo + .json. Wires into grunt/release.",
+  "keywords": [
+    "wordpress",
+    "i18n",
+    "l10n",
+    "translation",
+    "gettext",
+    "po",
+    "pot",
+    "ai",
+    "claude",
+    "grunt"
+  ],
+  "homepage": "https://github.com/vapvarun/wbcom-i18n-ai#readme",
+  "bugs": {
+    "url": "https://github.com/vapvarun/wbcom-i18n-ai/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vapvarun/wbcom-i18n-ai.git"
+  },
+  "bin": {
+    "wbcom-i18n": "bin/wbcom-i18n.js"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "bin/",
+    "lib/",
+    "grunt/",
+    "README.md",
+    ".wbcom-i18n.example.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "commonjs",
+  "dependencies": {
+    "gettext-parser": "^8.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "GPL-2.0-or-later",
+  "author": "Wbcom Designs"
+}