vbss-translator 1.0.2 → 1.1.0

package/dist/cli/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import{dirname as w,resolve as d,normalize as p,relative as $}from"path";import{glob as T}from"glob";import{mkdir as G,writeFile as O,readFile as F}from"fs/promises";import{watch as U,existsSync as _}from"fs";async function x(o){try{const t=await T(o,{cwd:process.cwd(),absolute:!1}),e=process.cwd();return t.map(n=>({path:d(e,n),relativePath:p(n).replace(/\\/g,"/"),translations:[]}))}catch(t){const e=t instanceof Error?t.message:"Unknown error";return[{path:"",relativePath:"",translations:[],error:{file:o,message:`Failed to discover files: ${e}`,type:"file_system"}}]}}async function j(o){const t=o.map(async e=>{if(e.error)return e;try{const n=await F(e.path,"utf-8"),s=JSON.parse(n),a=[];if(Array.isArray(s))for(const r of s){if(typeof r!="object"||r===null)return{...e,translations:[],error:{file:e.path,message:"Translation array must contain objects only",type:"validation"}};const u={};for(const[l,i]of Object.entries(r)){if(typeof i!="string")return{...e,translations:[],error:{file:e.path,message:`Translation value for key "${l}" must be a string, got ${typeof i}`,type:"validation"}};u[l]=i}a.push(u)}else if(typeof s=="object"&&s!==null){const r={};for(const[u,l]of Object.entries(s)){if(typeof l!="string")return{...e,translations:[],error:{file:e.path,message:`Translation value for key "${u}" must be a string, got ${typeof l}`,type:"validation"}};r[u]=l}return a.push(r),{...e,translations:a,wasSingleObject:!0}}else return{...e,translations:[],error:{file:e.path,message:"Translation file must contain a JSON object or array of objects",type:"validation"}};return{...e,translations:a}}catch(n){if(n instanceof SyntaxError)return{...e,translations:[],error:{file:e.path,message:`Invalid JSON: ${n.message}`,type:"invalid_json"}};const s=n instanceof Error?n.message:"Unknown error";return{...e,translations:[],error:{file:e.path,message:`Failed to read file: ${s}`,type:"file_system"}}}});return Promise.all(t)}function S(o){for(const t of o)if(!t.error&&t.translations.length>0)return Object.keys(t.translations[0]);return null}function B(o,t){const e=[];for(const n of o){if(n.error)continue;if(n.translations.length===0){e.push({file:n.path,message:"File has no translations",type:"validation"});continue}const s=Object.keys(n.translations[0]);for(let i=1;i<n.translations.length;i++){const f=Object.keys(n.translations[i]);if(JSON.stringify([...f].sort())!==JSON.stringify([...s].sort())){e.push({file:n.path,message:`Translation ${i+1} in file has different language keys`,type:"validation"});continue}}const a=[...s].sort(),r=[...t].sort(),u=r.filter(i=>!a.includes(i)),l=a.filter(i=>!r.includes(i));if(u.length>0||l.length>0){const i=[];u.length>0&&i.push(`missing languages: ${u.join(", ")}`),l.length>0&&i.push(`extra languages: ${l.join(", ")}`),e.push({file:n.path,message:`Language mismatch: ${i.join(", ")}. Expected: ${t.join(", ")}`,type:"missing_languages"})}}return e}function k(o,t){const e=new Set,n=[];for(const s of o){const a=s[t];if(a===void 0){n.push(s);continue}const r=a;e.has(r)||(e.add(r),n.push(s))}return n}function L(o,t){const e=w(o);let s=$(e,t);return s=p(s).replace(/\\/g,"/"),s.startsWith(".")||(s="./"+s),s}function P(o,t,e){const n=o.filter(f=>!f.error&&f.translations.length>0).sort((f,h)=>f.path.localeCompare(h.path));if(n.length===0)return`export default []
+`;const s=n.map((f,h)=>{const c=L(t,f.path);return`import translations${h} from '${c}' assert { type: 'json' };`}).join(`
+`),a=n.map((f,h)=>f.wasSingleObject?`  ...(Array.isArray(translations${h}) ? translations${h} : [translations${h}])`:`  ...translations${h}`).join(`,
+`),u=`export interface Translation {
+${e.map(f=>`  ${f}: string;`).join(`
+`)}
+  [key: string]: string;
+}`,l=e[0]||"en",i=n.length>0?`
+const uniqueTranslations = allTranslations.filter(
+  (translation, index, self) => index === self.findIndex((t) => t.${l} === translation.${l})
+);`:"";return`${s}
+
+${u}
+
+const allTranslations: Translation[] = [
+${a}
+];${i}
+
+export default uniqueTranslations;
+`}function A(o){const t=o.filter(r=>!r.error&&r.translations.length>0).sort((r,u)=>r.path.localeCompare(u.path));if(t.length===0)return`export default []
+`;const e=[];for(const r of t)r.wasSingleObject&&r.translations.length===1?e.push(r.translations[0]):e.push(...r.translations);const n=e.length>0?Object.keys(e[0])[0]:"en",s=e.map(r=>JSON.stringify(r,null,2).split(`
+`).map(i=>`  ${i}`).join(`
+`)).join(`,
+`),a=`
+const uniqueTranslations = allTranslations.filter(
+  (translation, index, self) => index === self.findIndex((t) => t.${n} === translation.${n})
+);`;return`const allTranslations = [
+${s}
+];${a}
+
+export default uniqueTranslations;
+`}function C(o,t,e){return P(o,t,e)}async function E(o){const t=[],e=Date.now(),n=await x(o.pattern);if(n.length===0)return{success:!0,filesFound:0,translationsGenerated:0,errors:[],outputPath:o.outputPath};for(const c of n)c.error&&t.push(c.error);const s=await j(n);for(const c of s)c.error&&t.push(c.error);const a=S(s);if((!a||a.length===0)&&s.filter(m=>!m.error&&m.translations.length>0).length===0)return{success:!1,filesFound:n.length,translationsGenerated:0,errors:t.length>0?t:[{file:o.pattern,message:"No valid translation files found",type:"validation"}],outputPath:o.outputPath};if(a&&a.length>0){const c=B(s,a);if(t.push(...c),c.length>0)return{success:!1,filesFound:n.length,translationsGenerated:0,errors:t,outputPath:o.outputPath}}const r=[];for(const c of s)!c.error&&c.translations.length>0&&r.push(...c.translations);const u=o.referenceLanguage||a?.[0]||"en",l=k(r,u);let i;const f=s.filter(c=>!c.error&&c.translations.length>0);switch(o.outputFormat){case"ts":i=P(f,o.outputPath,a||[]);break;case"tsx":i=C(f,o.outputPath,a||[]);break;case"js":i=A(f);break;default:return{success:!1,filesFound:n.length,translationsGenerated:0,errors:[...t,{file:o.outputPath,message:`Unsupported output format: ${o.outputFormat}`,type:"validation"}],outputPath:o.outputPath}}try{const c=w(o.outputPath);await G(c,{recursive:!0}),await O(o.outputPath,i,"utf-8")}catch(c){const m=c instanceof Error?c.message:"Unknown error";return t.push({file:o.outputPath,message:`Failed to write output file: ${m}`,type:"file_system"}),{success:!1,filesFound:n.length,translationsGenerated:l.length,errors:t,outputPath:o.outputPath}}const h=Date.now()-e;return h>1e3&&n.length<100&&console.warn(`⚠️  Generation took ${h}ms for ${n.length} files`),{success:t.length===0,filesFound:n.length,translationsGenerated:l.length,errors:t,outputPath:o.outputPath}}const R="src/**/translations.json",W="src/translations/index.ts",N="ts";class I{async loadFromFile(t){try{const e=d(t),n=await F(e,"utf-8");return JSON.parse(n)}catch(e){if(e&&typeof e=="object"&&"code"in e&&e.code==="ENOENT")return null;throw e instanceof SyntaxError?new Error(`Invalid JSON in config file: ${e.message}`):e}}loadFromArgs(t){const e={};return typeof t.pattern=="string"&&(e.pattern=t.pattern),typeof t.output=="string"&&(e.outputPath=t.output),typeof t.format=="string"&&(t.format==="ts"||t.format==="js"||t.format==="tsx")&&(e.outputFormat=t.format),typeof t["reference-language"]=="string"&&(e.referenceLanguage=t["reference-language"]),e}merge(t,e){const n={...t,...e};return{pattern:n.pattern??R,outputPath:n.outputPath??W,outputFormat:n.outputFormat??N,referenceLanguage:n.referenceLanguage}}}const y=new I,D=300;function J(o,t,e){try{const n=p(o),s=p(e);let a;try{a=$(s,n)}catch{a=$(e,o)}a=a.replace(/\\/g,"/");let r=t.replace(/\\/g,"/");r=r.replace(/\*\*\//g,"___GLOB_DOUBLE_STAR_SLASH___"),r=r.replace(/\*\*/g,"___GLOB_DOUBLE_STAR___"),r=r.replace(/\./g,"\\."),r=r.replace(/\*/g,"[^/]*"),r=r.replace(/\?/g,"[^/]"),r=r.replace(/___GLOB_DOUBLE_STAR_SLASH___/g,"(.*/)?"),r=r.replace(/___GLOB_DOUBLE_STAR___/g,".*");const l=new RegExp(`^${r}$`).test(a);return console.log(`[DEBUG] Pattern matching: "${a}" against "${r}" = ${l}`),l}catch(n){console.log("[DEBUG] Pattern matching failed, using fallback:",n);const s=$(e,o).replace(/\\/g,"/"),a=s.split("/"),r=a[a.length-1]==="translations.json"&&a[0]==="src";return console.log(`[DEBUG] Fallback pattern matching: "${s}" = ${r}`),r}}function M(o){const t=new Set;for(const e of o)t.add(w(e));return Array.from(t)}class z{watchers=new Map;debounceTimer=null;isWatching=!1;generatorOptions=null;callback=null;pattern="";cwd="";async watch(t,e){if(this.isWatching)throw new Error("Watch service is already watching");this.pattern=t,this.callback=e,this.cwd=p(process.cwd()),this.isWatching=!0;const n=await T(t,{cwd:this.cwd,absolute:!0}),s=M(n);s.length===0&&s.push(this.cwd);const a=s.map(u=>p(u));console.log(`[DEBUG] Watching ${a.length} directory(ies) for pattern: ${t}`);for(const u of a)console.log(`[DEBUG] Setting up watch for directory: ${u}`),this.watchDirectory(u);const r=p(this.cwd);this.watchers.has(r)||(console.log(`[DEBUG] Setting up watch for root directory: ${r}`),this.watchDirectory(r)),console.log(`[DEBUG] Total watchers active: ${this.watchers.size}`)}watchDirectory(t){const e=p(t);if(this.watchers.has(e)){console.log(`[DEBUG] Already watching directory: ${e}`);return}console.log(`[DEBUG] Starting watch on directory: ${e}`);const n=U(e,{recursive:!0},(s,a)=>{if(!a){console.log(`[DEBUG] Event received but filename is empty, eventType: ${s}`);return}console.log(`[DEBUG] File system event: ${s} on ${a} in ${e}`);let r;try{r=d(e,a),r=p(r)}catch{r=p(a)}console.log(`[DEBUG] Resolved file path: ${r}`),console.log(`[DEBUG] Pattern: ${this.pattern}, CWD: ${this.cwd}`);const u=J(r,this.pattern,this.cwd);if(console.log(`[DEBUG] Pattern match result: ${u}`),!u){console.log(`[DEBUG] File does not match pattern, ignoring: ${r}`);return}console.log("[DEBUG] File matches pattern! Processing event...");let l;if(s==="rename"){const i=_(r);l=i?"add":"delete",console.log(`[DEBUG] Rename event, file exists: ${i}, normalized to: ${l}`)}else s==="change"?(l="change",console.log("[DEBUG] Change event detected")):(l="change",console.log(`[DEBUG] Unknown event type: ${s}, defaulting to change`));if(l==="add"){const i=w(r),f=p(i);!this.watchers.has(f)&&f!==e&&(console.log(`[DEBUG] New file detected, ensuring directory is watched: ${f}`),this.watchDirectory(f))}console.log(`[DEBUG] Triggering regeneration for: ${r} (${l})`),this.debounceRegeneration(r,l)});this.watchers.set(e,n),n.on("error",s=>{console.error(`[DEBUG] Watch error in ${e}:`,s)}),console.log(`[DEBUG] Watch successfully set up for: ${e}`)}debounceRegeneration(t,e){console.log(`[DEBUG] debounceRegeneration called for: ${t} (${e})`),this.debounceTimer&&(console.log("[DEBUG] Clearing existing debounce timer"),clearTimeout(this.debounceTimer)),console.log(`[DEBUG] Setting new debounce timer (${D}ms)`),this.debounceTimer=setTimeout(async()=>{if(console.log("[DEBUG] Debounce timer fired, starting regeneration..."),!this.generatorOptions||!this.callback){console.log("[DEBUG] Missing generatorOptions or callback, aborting regeneration");return}try{console.log("[DEBUG] Calling generate with options:",{pattern:this.generatorOptions.pattern,outputPath:this.generatorOptions.outputPath,outputFormat:this.generatorOptions.outputFormat});const n=await E(this.generatorOptions),s=e;this.callback&&this.callback({type:s,file:t}),n.success?console.log(`✅ Regenerated translations (${n.translationsGenerated} translations from ${n.filesFound} file(s))`):console.error(`❌ Regeneration failed: ${n.errors.map(a=>a.message).join(", ")}`)}catch(n){const s=n instanceof Error?n.message:"Unknown error";console.error(`❌ Watch regeneration error: ${s}`)}},D)}setGeneratorOptions(t){this.generatorOptions=t}stop(){if(this.isWatching){this.debounceTimer&&(clearTimeout(this.debounceTimer),this.debounceTimer=null);for(const[,t]of this.watchers.entries())t.close();this.watchers.clear(),this.isWatching=!1,this.generatorOptions=null,this.callback=null}}}async function q(o){const t=new z;t.setGeneratorOptions(o),console.log("🔍 Watching for translation file changes...");const e=await E(o);e.success?console.log(`✅ Initial generation: ${e.translationsGenerated} translations from ${e.filesFound} file(s)`):console.error(`❌ Initial generation failed: ${e.errors.map(s=>s.message).join(", ")}`),await t.watch(o.pattern,()=>{});const n=()=>{console.log(`
+👋 Stopping watch mode...`),t.stop(),process.exit(0)};return process.on("SIGINT",n),process.on("SIGTERM",n),new Promise(()=>{})}var H={};const g={reset:"\x1B[0m",red:"\x1B[31m",green:"\x1B[32m",yellow:"\x1B[33m",blue:"\x1B[34m"},b={searching:"🔍",success:"✅",error:"❌",warning:"⚠️"};function V(o){const t={};let e=0;for(;e<o.length;){const n=o[e];if(n.startsWith("--")&&n.includes("=")){const[s,...a]=n.slice(2).split("="),r=a.join("=");t[s]=r||!0,e++;continue}if(n.startsWith("--")){const s=n.slice(2);e+1<o.length&&!o[e+1].startsWith("--")?(t[s]=o[e+1],e+=2):(t[s]=!0,e++);continue}if(n.startsWith("-")&&!n.startsWith("--")){const s=n.slice(1);t[s]=!0,e++;continue}e++}return t}function K(){const o=`
+${g.blue}vbss-translator generate${g.reset}
+Generate translation index files from translation JSON files.
+${g.yellow}Usage:${g.reset}
+  npx vbss-translator generate [options]
+  npm run generate-translations [options]
+${g.yellow}Options:${g.reset}
+  --pattern <glob>           Glob pattern to search for translation files
+                            (default: "src/**/translations.json")
+  --output <path>            Output file path
+                            (default: "src/translations/index.ts")
+  --format <ts|js|tsx>       Output format (default: "ts")
+  --watch, -w                Enable watch mode (runs continuously)
+  --config <path>            Path to config file
+                            (default: "vbss-translator.config.json")
+  --reference-language <lang> Reference language for deduplication
+  --help, -h                 Show this help message
+${g.yellow}Examples:${g.reset}
+  npx vbss-translator generate
+  npx vbss-translator generate --pattern "src/**/*.json" --output "src/translations.ts"
+  npx vbss-translator generate --format js --reference-language en
+${g.yellow}Configuration:${g.reset}
+  Create a "vbss-translator.config.json" file in your project root:
+  {
+    "pattern": "src/**/translations.json",
+    "outputPath": "src/translations/index.ts",
+    "outputFormat": "ts",
+    "referenceLanguage": "en"
+  }
+  CLI flags take precedence over config file settings.
+`;console.log(o)}function v(o){return`${g.red}${b.error} ${o}${g.reset}`}function X(o){return`${g.green}${b.success} ${o}${g.reset}`}function Y(o){return`${g.blue}${b.searching} ${o}${g.reset}`}async function Q(){const o=process.argv.slice(2),t=V(o);(t.help||t.h)&&(K(),process.exit(0));try{const e=typeof t.config=="string"?t.config:"vbss-translator.config.json",n=d(process.cwd(),e),s=await y.loadFromFile(n),a=y.loadFromArgs({pattern:t.pattern,output:t.output,format:t.format,"reference-language":t["reference-language"]}),r=y.merge(s||{},a);console.log(Y(`Searching for translation files matching: ${r.pattern}`));const u={pattern:r.pattern,outputPath:d(process.cwd(),r.outputPath),outputFormat:r.outputFormat,referenceLanguage:r.referenceLanguage,watch:t.watch===!0||t.w===!0};if(u.watch){await q(u);return}const l=Date.now(),i=await E(u),f=Date.now()-l;if(i.success)console.log(X(`Generated ${i.translationsGenerated} translations from ${i.filesFound} file(s)`)),console.log(`${g.green}Output:${g.reset} ${i.outputPath}`),console.log(`${g.green}Time:${g.reset} ${f}ms`),process.exit(0);else{console.error(v("Generation failed with errors:"));for(const c of i.errors)console.error(`${g.red}  ${c.type}:${g.reset} ${c.file}`),console.error(`  ${c.message}`);const h=i.errors.some(c=>c.type==="validation"||c.type==="missing_languages");process.exit(h?2:1)}}catch(e){const n=e instanceof Error?e.message:"Unknown error occurred";console.error(v(n)),e instanceof Error&&e.stack&&(console.error(`${g.red}Stack trace:${g.reset}`),console.error(e.stack)),process.exit(1)}}H.JEST_WORKER_ID||process.argv[1]&&(process.argv[1].includes("cli/index")||process.argv[1].includes("vbss-translator"))&&Q().catch(t=>{const e=t instanceof Error?t.message:"Unknown error occurred";console.error(v(`Fatal error: ${e}`)),process.exit(1)});

package/dist/generator.cjs

@@ -0,0 +1,32 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const y=require("glob"),d=require("fs/promises"),h=require("path");async function v(n){try{const r=await y.glob(n,{cwd:process.cwd(),absolute:!1}),t=process.cwd();return r.map(e=>({path:h.resolve(t,e),relativePath:h.normalize(e).replace(/\\/g,"/"),translations:[]}))}catch(r){const t=r instanceof Error?r.message:"Unknown error";return[{path:"",relativePath:"",translations:[],error:{file:n,message:`Failed to discover files: ${t}`,type:"file_system"}}]}}async function $(n){const r=n.map(async t=>{if(t.error)return t;try{const e=await d.readFile(t.path,"utf-8"),a=JSON.parse(e),o=[];if(Array.isArray(a))for(const s of a){if(typeof s!="object"||s===null)return{...t,translations:[],error:{file:t.path,message:"Translation array must contain objects only",type:"validation"}};const c={};for(const[u,i]of Object.entries(s)){if(typeof i!="string")return{...t,translations:[],error:{file:t.path,message:`Translation value for key "${u}" must be a string, got ${typeof i}`,type:"validation"}};c[u]=i}o.push(c)}else if(typeof a=="object"&&a!==null){const s={};for(const[c,u]of Object.entries(a)){if(typeof u!="string")return{...t,translations:[],error:{file:t.path,message:`Translation value for key "${c}" must be a string, got ${typeof u}`,type:"validation"}};s[c]=u}return o.push(s),{...t,translations:o,wasSingleObject:!0}}else return{...t,translations:[],error:{file:t.path,message:"Translation file must contain a JSON object or array of objects",type:"validation"}};return{...t,translations:o}}catch(e){if(e instanceof SyntaxError)return{...t,translations:[],error:{file:t.path,message:`Invalid JSON: ${e.message}`,type:"invalid_json"}};const a=e instanceof Error?e.message:"Unknown error";return{...t,translations:[],error:{file:t.path,message:`Failed to read file: ${a}`,type:"file_system"}}}});return Promise.all(r)}function j(n){for(const r of n)if(!r.error&&r.translations.length>0)return Object.keys(r.translations[0]);return null}function P(n,r){const t=[];for(const e of n){if(e.error)continue;if(e.translations.length===0){t.push({file:e.path,message:"File has no translations",type:"validation"});continue}const a=Object.keys(e.translations[0]);for(let i=1;i<e.translations.length;i++){const f=Object.keys(e.translations[i]);if(JSON.stringify([...f].sort())!==JSON.stringify([...a].sort())){t.push({file:e.path,message:`Translation ${i+1} in file has different language keys`,type:"validation"});continue}}const o=[...a].sort(),s=[...r].sort(),c=s.filter(i=>!o.includes(i)),u=o.filter(i=>!s.includes(i));if(c.length>0||u.length>0){const i=[];c.length>0&&i.push(`missing languages: ${c.join(", ")}`),u.length>0&&i.push(`extra languages: ${u.join(", ")}`),t.push({file:e.path,message:`Language mismatch: ${i.join(", ")}. Expected: ${r.join(", ")}`,type:"missing_languages"})}}return t}function T(n,r){const t=new Set,e=[];for(const a of n){const o=a[r];if(o===void 0){e.push(a);continue}const s=o;t.has(s)||(t.add(s),e.push(a))}return e}function b(n,r){const t=h.dirname(n),e=r;let a=h.relative(t,e);return a=h.normalize(a).replace(/\\/g,"/"),a.startsWith(".")||(a="./"+a),a}function m(n,r,t){const e=n.filter(f=>!f.error&&f.translations.length>0).sort((f,g)=>f.path.localeCompare(g.path));if(e.length===0)return`export default []
+`;const a=e.map((f,g)=>{const l=b(r,f.path);return`import translations${g} from '${l}' assert { type: 'json' };`}).join(`
+`),o=e.map((f,g)=>f.wasSingleObject?`  ...(Array.isArray(translations${g}) ? translations${g} : [translations${g}])`:`  ...translations${g}`).join(`,
+`),c=`export interface Translation {
+${t.map(f=>`  ${f}: string;`).join(`
+`)}
+  [key: string]: string;
+}`,u=t[0]||"en",i=e.length>0?`
+const uniqueTranslations = allTranslations.filter(
+  (translation, index, self) => index === self.findIndex((t) => t.${u} === translation.${u})
+);`:"";return`${a}
+
+${c}
+
+const allTranslations: Translation[] = [
+${o}
+];${i}
+
+export default uniqueTranslations;
+`}function F(n){const r=n.filter(s=>!s.error&&s.translations.length>0).sort((s,c)=>s.path.localeCompare(c.path));if(r.length===0)return`export default []
+`;const t=[];for(const s of r)s.wasSingleObject&&s.translations.length===1?t.push(s.translations[0]):t.push(...s.translations);const e=t.length>0?Object.keys(t[0])[0]:"en",a=t.map(s=>JSON.stringify(s,null,2).split(`
+`).map(i=>`  ${i}`).join(`
+`)).join(`,
+`),o=`
+const uniqueTranslations = allTranslations.filter(
+  (translation, index, self) => index === self.findIndex((t) => t.${e} === translation.${e})
+);`;return`const allTranslations = [
+${a}
+];${o}
+
+export default uniqueTranslations;
+`}function w(n,r,t){return m(n,r,t)}async function k(n){const r=[],t=Date.now(),e=await v(n.pattern);if(e.length===0)return{success:!0,filesFound:0,translationsGenerated:0,errors:[],outputPath:n.outputPath};for(const l of e)l.error&&r.push(l.error);const a=await $(e);for(const l of a)l.error&&r.push(l.error);const o=j(a);if((!o||o.length===0)&&a.filter(p=>!p.error&&p.translations.length>0).length===0)return{success:!1,filesFound:e.length,translationsGenerated:0,errors:r.length>0?r:[{file:n.pattern,message:"No valid translation files found",type:"validation"}],outputPath:n.outputPath};if(o&&o.length>0){const l=P(a,o);if(r.push(...l),l.length>0)return{success:!1,filesFound:e.length,translationsGenerated:0,errors:r,outputPath:n.outputPath}}const s=[];for(const l of a)!l.error&&l.translations.length>0&&s.push(...l.translations);const c=n.referenceLanguage||(o==null?void 0:o[0])||"en",u=T(s,c);let i;const f=a.filter(l=>!l.error&&l.translations.length>0);switch(n.outputFormat){case"ts":i=m(f,n.outputPath,o||[]);break;case"tsx":i=w(f,n.outputPath,o||[]);break;case"js":i=F(f);break;default:return{success:!1,filesFound:e.length,translationsGenerated:0,errors:[...r,{file:n.outputPath,message:`Unsupported output format: ${n.outputFormat}`,type:"validation"}],outputPath:n.outputPath}}try{const l=h.dirname(n.outputPath);await d.mkdir(l,{recursive:!0}),await d.writeFile(n.outputPath,i,"utf-8")}catch(l){const p=l instanceof Error?l.message:"Unknown error";return r.push({file:n.outputPath,message:`Failed to write output file: ${p}`,type:"file_system"}),{success:!1,filesFound:e.length,translationsGenerated:u.length,errors:r,outputPath:n.outputPath}}const g=Date.now()-t;return g>1e3&&e.length<100&&console.warn(`⚠️  Generation took ${g}ms for ${e.length} files`),{success:r.length===0,filesFound:e.length,translationsGenerated:u.length,errors:r,outputPath:n.outputPath}}exports.generate=k;

package/dist/generator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Programmatic API for vbss-translator generator
+ *
+ * This module is Node.js only and should not be imported in browser environments.
+ * Use this for build tool integrations (Vite plugins, Webpack loaders, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { generate } from 'vbss-translator/generator';
+ *
+ * const result = await generate({
+ *   pattern: 'src/**\/translations.json',
+ *   outputPath: 'src/translations/index.ts',
+ *   outputFormat: 'ts',
+ * });
+ * ```
+ */
+export { generate } from './cli/generator';
+export type { GeneratorOptions, GenerationResult, GenerationError, OutputFormat, TranslationRecord, } from './cli/types';

package/dist/generator.js

@@ -0,0 +1,360 @@
+import { glob as y } from "glob";
+import { mkdir as v, writeFile as $, readFile as j } from "fs/promises";
+import { dirname as p, resolve as F, normalize as d, relative as P } from "path";
+async function T(n) {
+  try {
+    const r = await y(n, { cwd: process.cwd(), absolute: !1 }), t = process.cwd();
+    return r.map((e) => ({
+      path: F(t, e),
+      relativePath: d(e).replace(/\\/g, "/"),
+      translations: []
+    }));
+  } catch (r) {
+    const t = r instanceof Error ? r.message : "Unknown error";
+    return [
+      {
+        path: "",
+        relativePath: "",
+        translations: [],
+        error: {
+          file: n,
+          message: `Failed to discover files: ${t}`,
+          type: "file_system"
+        }
+      }
+    ];
+  }
+}
+async function b(n) {
+  const r = n.map(async (t) => {
+    if (t.error)
+      return t;
+    try {
+      const e = await j(t.path, "utf-8"), a = JSON.parse(e), o = [];
+      if (Array.isArray(a))
+        for (const s of a) {
+          if (typeof s != "object" || s === null)
+            return {
+              ...t,
+              translations: [],
+              error: {
+                file: t.path,
+                message: "Translation array must contain objects only",
+                type: "validation"
+              }
+            };
+          const c = {};
+          for (const [u, i] of Object.entries(s)) {
+            if (typeof i != "string")
+              return {
+                ...t,
+                translations: [],
+                error: {
+                  file: t.path,
+                  message: `Translation value for key "${u}" must be a string, got ${typeof i}`,
+                  type: "validation"
+                }
+              };
+            c[u] = i;
+          }
+          o.push(c);
+        }
+      else if (typeof a == "object" && a !== null) {
+        const s = {};
+        for (const [c, u] of Object.entries(a)) {
+          if (typeof u != "string")
+            return {
+              ...t,
+              translations: [],
+              error: {
+                file: t.path,
+                message: `Translation value for key "${c}" must be a string, got ${typeof u}`,
+                type: "validation"
+              }
+            };
+          s[c] = u;
+        }
+        return o.push(s), {
+          ...t,
+          translations: o,
+          wasSingleObject: !0
+        };
+      } else
+        return {
+          ...t,
+          translations: [],
+          error: {
+            file: t.path,
+            message: "Translation file must contain a JSON object or array of objects",
+            type: "validation"
+          }
+        };
+      return {
+        ...t,
+        translations: o
+      };
+    } catch (e) {
+      if (e instanceof SyntaxError)
+        return {
+          ...t,
+          translations: [],
+          error: {
+            file: t.path,
+            message: `Invalid JSON: ${e.message}`,
+            type: "invalid_json"
+          }
+        };
+      const a = e instanceof Error ? e.message : "Unknown error";
+      return {
+        ...t,
+        translations: [],
+        error: {
+          file: t.path,
+          message: `Failed to read file: ${a}`,
+          type: "file_system"
+        }
+      };
+    }
+  });
+  return Promise.all(r);
+}
+function w(n) {
+  for (const r of n)
+    if (!r.error && r.translations.length > 0)
+      return Object.keys(r.translations[0]);
+  return null;
+}
+function k(n, r) {
+  const t = [];
+  for (const e of n) {
+    if (e.error)
+      continue;
+    if (e.translations.length === 0) {
+      t.push({
+        file: e.path,
+        message: "File has no translations",
+        type: "validation"
+      });
+      continue;
+    }
+    const a = Object.keys(e.translations[0]);
+    for (let i = 1; i < e.translations.length; i++) {
+      const f = Object.keys(e.translations[i]);
+      if (JSON.stringify([...f].sort()) !== JSON.stringify([...a].sort())) {
+        t.push({
+          file: e.path,
+          message: `Translation ${i + 1} in file has different language keys`,
+          type: "validation"
+        });
+        continue;
+      }
+    }
+    const o = [...a].sort(), s = [...r].sort(), c = s.filter(
+      (i) => !o.includes(i)
+    ), u = o.filter(
+      (i) => !s.includes(i)
+    );
+    if (c.length > 0 || u.length > 0) {
+      const i = [];
+      c.length > 0 && i.push(`missing languages: ${c.join(", ")}`), u.length > 0 && i.push(`extra languages: ${u.join(", ")}`), t.push({
+        file: e.path,
+        message: `Language mismatch: ${i.join(
+          ", "
+        )}. Expected: ${r.join(", ")}`,
+        type: "missing_languages"
+      });
+    }
+  }
+  return t;
+}
+function O(n, r) {
+  const t = /* @__PURE__ */ new Set(), e = [];
+  for (const a of n) {
+    const o = a[r];
+    if (o === void 0) {
+      e.push(a);
+      continue;
+    }
+    const s = o;
+    t.has(s) || (t.add(s), e.push(a));
+  }
+  return e;
+}
+function S(n, r) {
+  const t = p(n);
+  let a = P(t, r);
+  return a = d(a).replace(/\\/g, "/"), a.startsWith(".") || (a = "./" + a), a;
+}
+function m(n, r, t) {
+  const e = n.filter((f) => !f.error && f.translations.length > 0).sort((f, g) => f.path.localeCompare(g.path));
+  if (e.length === 0)
+    return `export default []
+`;
+  const a = e.map((f, g) => {
+    const l = S(r, f.path);
+    return `import translations${g} from '${l}' assert { type: 'json' };`;
+  }).join(`
+`), o = e.map((f, g) => f.wasSingleObject ? `  ...(Array.isArray(translations${g}) ? translations${g} : [translations${g}])` : `  ...translations${g}`).join(`,
+`), c = `export interface Translation {
+${t.map((f) => `  ${f}: string;`).join(`
+`)}
+  [key: string]: string;
+}`, u = t[0] || "en", i = e.length > 0 ? `
+const uniqueTranslations = allTranslations.filter(
+  (translation, index, self) => index === self.findIndex((t) => t.${u} === translation.${u})
+);` : "";
+  return `${a}
+
+${c}
+
+const allTranslations: Translation[] = [
+${o}
+];${i}
+
+export default uniqueTranslations;
+`;
+}
+function x(n) {
+  const r = n.filter((s) => !s.error && s.translations.length > 0).sort((s, c) => s.path.localeCompare(c.path));
+  if (r.length === 0)
+    return `export default []
+`;
+  const t = [];
+  for (const s of r)
+    s.wasSingleObject && s.translations.length === 1 ? t.push(s.translations[0]) : t.push(...s.translations);
+  const e = t.length > 0 ? Object.keys(t[0])[0] : "en", a = t.map((s) => JSON.stringify(s, null, 2).split(`
+`).map((i) => `  ${i}`).join(`
+`)).join(`,
+`), o = `
+const uniqueTranslations = allTranslations.filter(
+  (translation, index, self) => index === self.findIndex((t) => t.${e} === translation.${e})
+);`;
+  return `const allTranslations = [
+${a}
+];${o}
+
+export default uniqueTranslations;
+`;
+}
+function L(n, r, t) {
+  return m(n, r, t);
+}
+async function N(n) {
+  const r = [], t = Date.now(), e = await T(n.pattern);
+  if (e.length === 0)
+    return {
+      success: !0,
+      filesFound: 0,
+      translationsGenerated: 0,
+      errors: [],
+      outputPath: n.outputPath
+    };
+  for (const l of e)
+    l.error && r.push(l.error);
+  const a = await b(e);
+  for (const l of a)
+    l.error && r.push(l.error);
+  const o = w(a);
+  if ((!o || o.length === 0) && a.filter(
+    (h) => !h.error && h.translations.length > 0
+  ).length === 0)
+    return {
+      success: !1,
+      filesFound: e.length,
+      translationsGenerated: 0,
+      errors: r.length > 0 ? r : [
+        {
+          file: n.pattern,
+          message: "No valid translation files found",
+          type: "validation"
+        }
+      ],
+      outputPath: n.outputPath
+    };
+  if (o && o.length > 0) {
+    const l = k(a, o);
+    if (r.push(...l), l.length > 0)
+      return {
+        success: !1,
+        filesFound: e.length,
+        translationsGenerated: 0,
+        errors: r,
+        outputPath: n.outputPath
+      };
+  }
+  const s = [];
+  for (const l of a)
+    !l.error && l.translations.length > 0 && s.push(...l.translations);
+  const c = n.referenceLanguage || (o == null ? void 0 : o[0]) || "en", u = O(
+    s,
+    c
+  );
+  let i;
+  const f = a.filter(
+    (l) => !l.error && l.translations.length > 0
+  );
+  switch (n.outputFormat) {
+    case "ts":
+      i = m(
+        f,
+        n.outputPath,
+        o || []
+      );
+      break;
+    case "tsx":
+      i = L(
+        f,
+        n.outputPath,
+        o || []
+      );
+      break;
+    case "js":
+      i = x(f);
+      break;
+    default:
+      return {
+        success: !1,
+        filesFound: e.length,
+        translationsGenerated: 0,
+        errors: [
+          ...r,
+          {
+            file: n.outputPath,
+            message: `Unsupported output format: ${n.outputFormat}`,
+            type: "validation"
+          }
+        ],
+        outputPath: n.outputPath
+      };
+  }
+  try {
+    const l = p(n.outputPath);
+    await v(l, { recursive: !0 }), await $(n.outputPath, i, "utf-8");
+  } catch (l) {
+    const h = l instanceof Error ? l.message : "Unknown error";
+    return r.push({
+      file: n.outputPath,
+      message: `Failed to write output file: ${h}`,
+      type: "file_system"
+    }), {
+      success: !1,
+      filesFound: e.length,
+      translationsGenerated: u.length,
+      errors: r,
+      outputPath: n.outputPath
+    };
+  }
+  const g = Date.now() - t;
+  return g > 1e3 && e.length < 100 && console.warn(
+    `⚠️  Generation took ${g}ms for ${e.length} files`
+  ), {
+    success: r.length === 0,
+    filesFound: e.length,
+    translationsGenerated: u.length,
+    errors: r,
+    outputPath: n.outputPath
+  };
+}
+export {
+  N as generate
+};

package/dist/vbss-translator.d.ts

@@ -1,25 +1,138 @@
 import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
 
-declare type Translation = {
-    [key: string]: string;
+declare type CacheConfig = {
+    enabled: boolean;
+    ttlMs: number;
+    maxEntries?: number;
+};
+
+export declare const createTranslationProvider: (config: ProviderConfig) => TranslationProvider;
+
+declare type CustomProviderConfig = {
+    readonly id: "custom";
+    readonly implementation?: TranslationProvider;
+    readonly factory?: CustomProviderFactory;
+    readonly options?: Record<string, unknown>;
+};
+
+declare type CustomProviderFactory = () => TranslationProvider;
+
+declare type ExternalTranslationCallbacks = {
+    shouldTranslate?: (request: ExternalTranslationRequest) => boolean;
+    onExternalTranslation?: (request: ExternalTranslationRequest) => void | boolean | Promise<void | boolean>;
+    onTranslationError?: (event: ExternalTranslationErrorEvent) => void;
+    onTranslationComplete?: (result: TranslateResult) => void;
+};
+
+declare type ExternalTranslationConfig = ExternalTranslationCallbacks & {
+    enabled: boolean;
+    provider: ProviderConfig;
+    cache: CacheConfig;
+    alwaysExternalKeys: ReadonlySet<string>;
+    timeoutMs: number;
+    debug?: boolean;
+};
+
+declare type ExternalTranslationConfigInput = Partial<Omit<ExternalTranslationConfig, "alwaysExternalKeys">> & {
+    alwaysExternalKeys?: ReadonlyArray<string> | ReadonlySet<string>;
+};
+
+declare type ExternalTranslationErrorEvent = {
+    key: string;
+    language: string;
+    error: ProviderError;
+    originalText: string;
+};
+
+declare type ExternalTranslationRequest = {
+    key: string;
+    text: string;
+    targetLanguage: string;
+    sourceLanguage?: string;
+};
+
+declare type GoogleProviderConfig = {
+    readonly id: "google";
+    readonly apiKey?: string;
+    readonly endpoint?: string;
+    readonly projectId?: string;
+    readonly region?: string;
+    readonly headers?: Record<string, string>;
+};
+
+declare type ProviderAvailability = {
+    available: boolean;
+    reason?: string;
+};
+
+declare type ProviderConfig = GoogleProviderConfig | CustomProviderConfig;
+
+declare type ProviderError = {
+    code: string;
+    message: string;
+    retryable: boolean;
+    details?: unknown;
+};
+
+declare type ProviderId = "google" | "custom";
+
+declare type TranslateOptions = {
+    preferExternal?: boolean;
+    sourceLanguage?: string;
+    fallbackValue?: string;
+    signal?: AbortSignal;
+};
+
+declare type TranslateRequest = {
+    text: string;
+    sourceLanguage: string;
+    targetLanguage: string;
+    glossary?: Record<string, string>;
+};
+
+declare type TranslateResult = {
+    translatedText: string;
+    detectedSourceLanguage?: string;
+    providerMetadata?: Record<string, string>;
+};
+
+declare type Translation = Record<string, string>;
+
+export declare interface TranslationProvider {
+    readonly type: ProviderId;
+    translate(request: TranslateRequest, options?: TranslationProviderTranslateOptions): Promise<TranslateResult>;
+    isAvailable?(): ProviderAvailability;
+    normalizeError?(error: unknown): ProviderError;
+}
+
+declare type TranslationProviderTranslateOptions = {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly headers?: Record<string, string>;
 };
 
 declare type TranslatorContextType = {
-    t: (key: string) => string;
+    t: (key: string, options?: TranslateOptions) => string;
     language: string;
     languages: string[];
     setLanguage: (language: string) => void;
+    isTranslating: Record<string, boolean>;
+    isTranslatingAny: boolean;
+    registerExternalKey: (key: string) => void;
+    externalConfig: ExternalTranslationConfig;
 };
 
-export declare const TranslatorProvider: ({ children, translations, defaultLanguage, persist, persistKey, autoDetectLanguage }: TranslatorProviderType) => JSX_2.Element;
+export declare const TranslatorProvider: ({ children, translations, defaultLanguage, persist, persistKey, autoDetectLanguage, externalTranslation, }: TranslatorProviderType) => JSX_2.Element;
 
 declare type TranslatorProviderType = {
-    children: React.ReactNode;
+    children: ReactNode;
     translations: Translation[];
     defaultLanguage?: string;
     persist?: boolean;
     persistKey?: string;
     autoDetectLanguage?: boolean;
+    externalTranslation?: ExternalTranslationConfigInput;
 };
 
 export declare const useTranslator: () => TranslatorContextType;