vanilla-builder 0.2.0 → 0.3.0

package/src/js.js

@@ -4,12 +4,13 @@ import fs from 'node:fs';
 import * as esbuild from 'esbuild';
 import * as acorn from 'acorn';
 import * as walk from 'acorn-walk';
-import { analyzeJs, compareGlobals } from './jsinfo.js';
+import { analyzeJs, compareGlobals, isolateTempGlobals } from './jsinfo.js';
 import { importOptional } from './optional.js';
 import { replaceWithMap } from './sourcemap.js';
 import { relFrom, toPosix, BuildError, rootPrefix, hasOwn, shortHash, jsOutPath } from './util.js';
 import { classifyUrl } from './urls.js';
 import { formatMessage, esbuildErrorText } from './css.js';
+import { L } from './i18n.js';
 
 /** Marcador de "raíz de salida" que se sustituye por la ruta relativa real de cada archivo generado. */
 export const MARK = '__VB_ROOT__';
@@ -55,50 +56,75 @@ export async function processClassic(ctx, { code, id, info, obfuscate, sourcemap
   const notes = [];
   let out = code;
   let map = null;
+  let allowPrefix = null;
   if (js.minify) {
     const auto = await targetForLevel(info.level);
-    const attempts = [{ target: js.target === 'auto' ? auto : js.target, keepNames: js.keepNames, label: 'completa' }];
-    if (js.target !== 'auto' || js.keepNames) attempts.push({ target: auto, keepNames: false, label: 'sin transpilar' });
-    attempts.push({ target: auto, keepNames: false, whitespace: true, label: 'solo espacios' });
+    const attempts = [{ target: js.target === 'auto' ? auto : js.target, keepNames: js.keepNames, label: L('completa', 'full') }];
+    if (js.target !== 'auto' || js.keepNames) attempts.push({ target: auto, keepNames: false, label: L('sin transpilar', 'without transpiling') });
+    attempts.push({ target: auto, keepNames: false, whitespace: true, label: L('solo espacios', 'whitespace only') });
     let done = false;
+    // Mismo prefijo que usa el ofuscador para sus nombres: las comprobaciones posteriores ya lo aceptan.
+    const tempPrefix = `_${shortHash(id, 6)}`;
+    const transform = (input, a, extra = {}) =>
+      esbuild.transform(input, {
+        loader: 'js',
+        target: a.target,
+        charset: 'ascii',
+        supported: SUPPORTED,
+        legalComments: js.legalComments,
+        drop: js.drop,
+        define: js.define,
+        keepNames: a.keepNames,
+        sourcemap: sourcemap ? 'external' : false,
+        sourcefile: id,
+        ...(a.whitespace ? { minifyWhitespace: true } : { minify: true }),
+        logLevel: 'silent',
+        ...extra,
+      });
     for (const a of attempts) {
       try {
-        const r = await esbuild.transform(code, {
-          loader: 'js',
-          target: a.target,
-          charset: 'ascii',
-          supported: SUPPORTED,
-          legalComments: js.legalComments,
-          drop: js.drop,
-          define: js.define,
-          keepNames: a.keepNames,
-          sourcemap: sourcemap ? 'external' : false,
-          sourcefile: id,
-          ...(a.whitespace ? { minifyWhitespace: true } : { minify: true }),
-          logLevel: 'silent',
-        });
-        const cmp = compareGlobals(info.top, r.code);
+        const r = await transform(code, a);
+        let candidate = r.code;
+        let cmp = compareGlobals(info.top, candidate);
+        let isolated = false;
+        if (!cmp.ok && !a.whitespace && a.target !== auto) {
+          // Al adaptar la sintaxis, esbuild declara temporales globales (var _a). Se adapta sin minificar
+          // (nombres reconocibles), se aíslan con un prefijo propio del archivo y después se minifica:
+          // la minificación no renombra globales de un script clásico ni crea temporales nuevas.
+          const lowered = await transform(code, a, { minify: false, minifyWhitespace: false, sourcemap: false });
+          const iso = isolateTempGlobals(lowered.code, info.top, tempPrefix);
+          if (iso) {
+            const r2 = await transform(iso, a, { sourcemap: false });
+            const cmp2 = compareGlobals(info.top, r2.code, tempPrefix);
+            if (cmp2.ok) {
+              candidate = r2.code;
+              cmp = cmp2;
+              isolated = true;
+            }
+          }
+        }
         if (cmp.ok) {
-          out = r.code;
-          map = r.map || null;
+          out = candidate;
+          map = isolated ? null : r.map || null;
+          if (isolated) allowPrefix = tempPrefix;
           done = true;
           break;
         }
-        notes.push(`minificación ${a.label} descartada: ${cmp.reason}`);
+        notes.push(L(`minificación ${a.label} descartada: ${cmp.reason}`, `${a.label} minification discarded: ${cmp.reason}`));
       } catch (err) {
-        notes.push(`minificación ${a.label} falló: ${firstLine(err)}`);
+        notes.push(L(`minificación ${a.label} falló: ${firstLine(err)}`, `${a.label} minification failed: ${firstLine(err)}`));
       }
     }
-    if (!done) notes.push('se deja sin minificar para no romperlo');
+    if (!done) notes.push(L('se deja sin minificar para no romperlo', 'left unminified so it does not break'));
   }
   if (obfuscate) {
     const o = await ctx.heavy.obfuscate(out, { isModule: false, options: ctx.obfuscatorOptions, id, globals: info.top });
     if (o.code) {
       out = o.code;
       map = null;
-    } else notes.push(`no se ofuscó: ${o.reason}`);
+    } else notes.push(L(`no se ofuscó: ${o.reason}`, `not obfuscated: ${o.reason}`));
   } else if (out !== code) {
-    const t = await terserPass(ctx, out, { isModule: false, level: info.level, globals: info.top });
+    const t = await terserPass(ctx, out, { isModule: false, level: info.level, globals: info.top, allowPrefix });
     if (t !== out) {
       out = t;
       map = null;
@@ -133,7 +159,7 @@ export async function processModuleStandalone(ctx, { code, id, info, obfuscate,
       out = r.code;
       map = r.map || null;
     } catch (err) {
-      notes.push(`no se pudo minificar: ${firstLine(err)}`);
+      notes.push(L(`no se pudo minificar: ${firstLine(err)}`, `could not minify: ${firstLine(err)}`));
     }
   }
   if (obfuscate) {
@@ -141,7 +167,7 @@ export async function processModuleStandalone(ctx, { code, id, info, obfuscate,
     if (o.code) {
       out = o.code;
       map = null;
-    } else notes.push(`no se ofuscó: ${o.reason}`);
+    } else notes.push(L(`no se ofuscó: ${o.reason}`, `not obfuscated: ${o.reason}`));
   } else if (out !== code) {
     const t = await terserPass(ctx, out, { isModule: true, level: info.level });
     if (t !== out) {
@@ -155,7 +181,7 @@ export async function processModuleStandalone(ctx, { code, id, info, obfuscate,
 /** Ofusca un módulo ya generado (paquete, chunk o worker). */
 export async function obfuscateModule(ctx, code, id) {
   const o = await ctx.heavy.obfuscate(code, { isModule: true, options: ctx.obfuscatorOptions, id });
-  return o.code ? { code: o.code } : { code, note: `no se ofuscó: ${o.reason}` };
+  return o.code ? { code: o.code } : { code, note: L(`no se ofuscó: ${o.reason}`, `not obfuscated: ${o.reason}`) };
 }
 
 /** Aplica un import map (solo "imports"; con "scopes" se usa el modo sin empaquetar). */
@@ -219,8 +245,10 @@ function modulePlugin(ctx, group, state) {
     if (!info.ok) return code;
     state.levels.push(info.level ?? 9999);
     if (!local) return code;
-    for (const u of info.unsafeUrls) state.unsafe.push(`new URL(variable, import.meta.url) en ${id}: ${u}`);
-    for (const u of info.unsafeImports) state.unsafe.push(`import() con una ruta calculada en ${id}: ${u}`);
+    for (const u of info.unsafeUrls)
+      state.unsafe.push(L(`new URL(variable, import.meta.url) en ${id}: ${u}`, `new URL(variable, import.meta.url) in ${id}: ${u}`));
+    for (const u of info.unsafeImports)
+      state.unsafe.push(L(`import() con una ruta calculada en ${id}: ${u}`, `import() with a computed path in ${id}: ${u}`));
     if (state.mode === 'scan') ctx.noteJsInfo(id, info, baseDir, { module: true });
     if (!info.urls.length) return code;
     let out = '';
@@ -287,18 +315,30 @@ function modulePlugin(ctx, group, state) {
             ctx.reportBroken(importer, spec, r);
             return { path: spec, external: true };
           }
-          ctx.requireStandalone(r.rel, `importado como CSS desde ${importer}`);
+          ctx.requireStandalone(r.rel, L(`importado como CSS desde ${importer}`, `imported as CSS from ${importer}`));
           return { path: `${MARK}/${r.rel}`, external: true };
         }
         const mapped = mapSpecifier(ctx, group.importMap, spec, baseDir);
         if (mapped?.external) return { path: spec, external: true };
         if (mapped?.rel) return { path: ctx.abs(mapped.rel) };
         if (mapped?.abs) return { path: mapped.abs };
-        if (mapped?.broken) return { errors: [{ text: `El import map de la página apunta "${spec}" a "${mapped.target}", que no existe.` }] };
+        if (mapped?.broken)
+          return {
+            errors: [
+              {
+                text: L(
+                  `El import map de la página apunta "${spec}" a "${mapped.target}", que no existe.`,
+                  `The page import map points "${spec}" to "${mapped.target}", which does not exist.`,
+                ),
+              },
+            ],
+          };
         if (spec.startsWith('/')) {
           const r = ctx.resolve(spec, baseDir);
           if (r.status === 'ok') return { path: ctx.abs(r.rel) };
-          return { errors: [{ text: `No existe "${spec}" (importado desde ${importer}).` }] };
+          return {
+            errors: [{ text: L(`No existe "${spec}" (importado desde ${importer}).`, `"${spec}" does not exist (imported from ${importer}).`) }],
+          };
         }
         return undefined;
       };
@@ -324,17 +364,21 @@ let terser = null;
 
 /** Carga terser (opcional) para la compresión máxima. */
 export async function ensureTerser(projectRoot) {
-  terser = await importOptional('terser', projectRoot, 'para la compresión máxima (js.minifier: "terser")');
+  terser = await importOptional(
+    'terser',
+    projectRoot,
+    L('para la compresión máxima (js.minifier: "terser")', 'for maximum compression (js.minifier: "terser")'),
+  );
 }
 
 /**
  * Segunda pasada con terser (varias pasadas de compresión). Solo se acepta si el resultado
  * es más pequeño y conserva globales (scripts) o exportaciones/importaciones (módulos).
  */
-export async function terserPass(ctx, code, { isModule, level, globals }) {
+export async function terserPass(ctx, code, { isModule, level, globals, allowPrefix = null }) {
   const js = ctx.cfg.js;
   if (!terser || js.minifier !== 'terser' || !js.minify || ctx.cfg.sourcemap) return code;
-  return ctx.heavy.terser(code, { isModule, level, globals: isModule ? undefined : globals, keepNames: js.keepNames });
+  return ctx.heavy.terser(code, { isModule, level, globals: isModule ? undefined : globals, allowPrefix, keepNames: js.keepNames });
 }
 
 /** Bytes de origen que aportaron código a una salida (incluye paquetes de node_modules). */
@@ -462,16 +506,23 @@ export async function buildModuleGroup(ctx, group) {
   try {
     scan = await esbuild.build({ ...common, target: 'esnext', plugins: [modulePlugin(ctx, group, scanState)] });
   } catch (err) {
-    throw new BuildError('No se pudieron empaquetar los módulos JavaScript:', esbuildErrorText(err, ctx.root).split('\n'));
+    throw new BuildError(
+      L('No se pudieron empaquetar los módulos JavaScript:', 'Could not bundle the JavaScript modules:'),
+      esbuildErrorText(err, ctx.root).split('\n'),
+    );
   }
   const inputs = Object.keys(scan.metafile.inputs)
     .map((p) => relFrom(ctx.root, path.resolve(ctx.root, p)))
     .filter((rel) => rel && ctx.files.has(rel));
   const dynamicWarnings = scan.warnings.filter((w) => w.id === 'unsupported-dynamic-import');
   let reason = null;
-  if (!cfg.js.bundle) reason = 'js.bundle está desactivado';
+  if (!cfg.js.bundle) reason = L('js.bundle está desactivado', 'js.bundle is disabled');
   else if (group.forcePerFile) reason = group.forcePerFile;
-  else if (dynamicWarnings.length) reason = `hay import() con rutas que no se pueden seguir (${formatMessage(dynamicWarnings[0], ctx.root)})`;
+  else if (dynamicWarnings.length)
+    reason = L(
+      `hay import() con rutas que no se pueden seguir (${formatMessage(dynamicWarnings[0], ctx.root)})`,
+      `there are import() calls with paths that cannot be followed (${formatMessage(dynamicWarnings[0], ctx.root)})`,
+    );
   else if (scanState.unsafe.length) reason = scanState.unsafe[0];
   if (reason) return { mode: 'per-file', reason, inputs, consumed: new Set() };
   for (const w of scan.warnings) ctx.warn(`JS: ${formatMessage(w, ctx.root)}`);
@@ -486,7 +537,10 @@ export async function buildModuleGroup(ctx, group) {
       emitState.vendorOut = vendor.outByAbs;
     } catch (err) {
       ctx.warn(
-        `no se pudieron separar las dependencias en archivos vendor (${esbuildErrorText(err, ctx.root).split('\n')[0]}); van dentro del paquete y se ofuscarán con él`,
+        L(
+          `no se pudieron separar las dependencias en archivos vendor (${esbuildErrorText(err, ctx.root).split('\n')[0]}); van dentro del paquete y se ofuscarán con él`,
+          `could not split dependencies into vendor files (${esbuildErrorText(err, ctx.root).split('\n')[0]}); they stay in the bundle and will be obfuscated with it`,
+        ),
       );
     }
   }
@@ -502,7 +556,10 @@ export async function buildModuleGroup(ctx, group) {
       plugins: [modulePlugin(ctx, group, emitState)],
     });
   } catch (err) {
-    throw new BuildError('No se pudieron empaquetar los módulos JavaScript:', esbuildErrorText(err, ctx.root).split('\n'));
+    throw new BuildError(
+      L('No se pudieron empaquetar los módulos JavaScript:', 'Could not bundle the JavaScript modules:'),
+      esbuildErrorText(err, ctx.root).split('\n'),
+    );
   }
   const maps = new Map();
   const files = [];

package/src/jsinfo.js

@@ -1,6 +1,7 @@
 // Análisis estático de JavaScript con acorn: nivel de sintaxis, globales, workers y rutas.
 import * as acorn from 'acorn';
 import * as walk from 'acorn-walk';
+import { L } from './i18n.js';
 
 const VERSIONS = [5, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025, 2026];
 const LATEST = 'latest';
@@ -249,6 +250,51 @@ export function checkSyntax(code, isModule) {
   }
 }
 
+// Nombres que esbuild crea al adaptar sintaxis a navegadores antiguos: temporales (_a, _b2) y ayudantes (__async).
+const ESBUILD_TEMP = /^(_[a-z]\d*|__[A-Za-z]+\d*)$/;
+
+/**
+ * Al transpilar un script clásico, esbuild puede declarar temporales en el ámbito global (var _a).
+ * Si TODAS las globales nuevas son de ese tipo, se renombran en todo el archivo a `${prefix}nombre`
+ * (único por archivo), así no pueden chocar con otros scripts. Devuelve el código nuevo, o null si no aplica.
+ * El renombrado es consistente en todos los ámbitos, así que no cambia el significado del código.
+ */
+export function isolateTempGlobals(code, before, prefix) {
+  let ast;
+  try {
+    ast = parse(code, 'script', LATEST);
+  } catch {
+    return null;
+  }
+  const top = globalBindings(
+    ast,
+    ast.body.some((s) => s.directive === 'use strict'),
+  );
+  const fresh = [...top.keys()].filter((n) => !before.has(n));
+  if (!fresh.length || !fresh.every((n) => ESBUILD_TEMP.test(n))) return null;
+  const rename = new Map(fresh.map((n) => [n, `${prefix}${n}`]));
+  const edits = new Map();
+  walk.fullAncestor(ast, (node, _state, ancestors) => {
+    if (node.type !== 'Identifier' || !rename.has(node.name)) return;
+    const p = ancestors[ancestors.length - 2];
+    const to = rename.get(node.name);
+    if (p) {
+      if (p.type === 'MemberExpression' && p.property === node && !p.computed) return;
+      if (p.type === 'Property' && p.shorthand) {
+        // { _a } → { _a: nuevo }: la clave se conserva, el valor se renombra.
+        edits.set(node.start, { start: node.start, end: node.end, text: `${node.name}: ${to}` });
+        return;
+      }
+      if ((p.type === 'Property' || p.type === 'MethodDefinition' || p.type === 'PropertyDefinition') && p.key === node && !p.computed) return;
+      if (p.type === 'LabeledStatement' || p.type === 'BreakStatement' || p.type === 'ContinueStatement') return;
+    }
+    if (!edits.has(node.start)) edits.set(node.start, { start: node.start, end: node.end, text: to });
+  });
+  let out = code;
+  for (const e of [...edits.values()].sort((a, b) => b.start - a.start)) out = out.slice(0, e.start) + e.text + out.slice(e.end);
+  return out;
+}
+
 /**
  * Compara las globales de un script antes y después de transformarlo.
  * `allowPrefix` permite nombres nuevos con ese prefijo (los que añade el ofuscador).
@@ -259,7 +305,7 @@ export function compareGlobals(before, afterCode, allowPrefix = null) {
   try {
     ast = parse(afterCode, 'script', LATEST);
   } catch (err) {
-    return { ok: false, reason: `el resultado no es JS válido (${err.message})` };
+    return { ok: false, reason: L(`el resultado no es JS válido (${err.message})`, `the result is not valid JS (${err.message})`) };
   }
   const after = {
     top: globalBindings(
@@ -268,12 +314,25 @@ export function compareGlobals(before, afterCode, allowPrefix = null) {
     ),
   };
   for (const [name, kind] of before) {
-    if (!after.top.has(name)) return { ok: false, reason: `desaparece la global "${name}"` };
-    if (after.top.get(name) !== kind) return { ok: false, reason: `la global "${name}" cambia de tipo (${kind} → ${after.top.get(name)})` };
+    if (!after.top.has(name)) return { ok: false, reason: L(`desaparece la global "${name}"`, `the global "${name}" disappears`) };
+    if (after.top.get(name) !== kind)
+      return {
+        ok: false,
+        reason: L(
+          `la global "${name}" cambia de tipo (${kind} → ${after.top.get(name)})`,
+          `the global "${name}" changes kind (${kind} → ${after.top.get(name)})`,
+        ),
+      };
   }
   for (const name of after.top.keys()) {
     if (!before.has(name) && !(allowPrefix && name.startsWith(allowPrefix)))
-      return { ok: false, reason: `aparece una global nueva "${name}" que podría chocar con otros scripts` };
+      return {
+        ok: false,
+        reason: L(
+          `aparece una global nueva "${name}" que podría chocar con otros scripts`,
+          `a new global "${name}" appears that could clash with other scripts`,
+        ),
+      };
   }
   return { ok: true };
 }

package/src/obfuscate.js

@@ -3,6 +3,7 @@ import * as acorn from 'acorn';
 import { shortHash } from './util.js';
 import { compareGlobals, moduleShape, checkSyntax } from './jsinfo.js';
 import { importOptional } from './optional.js';
+import { L } from './i18n.js';
 
 // Nunca se activan solos: cambian el comportamiento o rompen código que comparte globales.
 const FORCED_SAFE = { renameGlobals: false, renameProperties: false, sourceMap: false, target: 'browser' };
@@ -101,7 +102,7 @@ let engine = null;
 /** Carga javascript-obfuscator (instalado junto a Builder o en el proyecto). */
 export async function ensureObfuscator(projectRoot) {
   if (!engine) {
-    const mod = await importOptional('javascript-obfuscator', projectRoot, 'para ofuscar el JavaScript');
+    const mod = await importOptional('javascript-obfuscator', projectRoot, L('para ofuscar el JavaScript', 'to obfuscate JavaScript'));
     engine = mod.default ?? mod;
   }
   return engine;
@@ -143,15 +144,18 @@ export function obfuscateSafe(code, { isModule, options, id, globals }) {
   try {
     out = engine.obfuscate(body, opts).getObfuscatedCode();
   } catch (err) {
-    return { code: null, reason: `el ofuscador falló (${String(err.message).split('\n')[0]})` };
+    return {
+      code: null,
+      reason: L(`el ofuscador falló (${String(err.message).split('\n')[0]})`, `the obfuscator failed (${String(err.message).split('\n')[0]})`),
+    };
   }
   if (isModule) {
     const err = checkSyntax(out, true);
-    if (err) return { code: null, reason: `resultado inválido (${err})` };
+    if (err) return { code: null, reason: L(`resultado inválido (${err})`, `invalid result (${err})`) };
     const a = moduleShape(body);
     const b = moduleShape(out);
     if (!a || !b || a.exports !== b.exports || a.imports !== b.imports)
-      return { code: null, reason: 'cambiaron las exportaciones o importaciones del módulo' };
+      return { code: null, reason: L('cambiaron las exportaciones o importaciones del módulo', 'the module exports or imports changed') };
   } else {
     const cmp = compareGlobals(globals, out, prefix);
     if (!cmp.ok) return { code: null, reason: cmp.reason };

package/src/optional.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { BuildError } from './util.js';
+import { L } from './i18n.js';
 
 const cache = new Map();
 
@@ -25,9 +26,12 @@ export async function importOptional(name, projectRoot, purpose) {
     }
   }
   if (!mod)
-    throw new BuildError(`Falta el paquete opcional "${name}" ${purpose}.`, [
-      `Instálalo una vez con:  npm install --save-dev ${name}`,
-      'Builder lo carga solo cuando hace falta, por eso no viene incluido (así la instalación base es ligera).',
+    throw new BuildError(L(`Falta el paquete opcional "${name}" ${purpose}.`, `Missing optional package "${name}" ${purpose}.`), [
+      L(`Instálalo una vez con:  npm install --save-dev ${name}`, `Install it once with:  npm install --save-dev ${name}`),
+      L(
+        'Builder lo carga solo cuando hace falta, por eso no viene incluido (así la instalación base es ligera).',
+        'Builder loads it only when needed, so it is not bundled (this keeps the base install small).',
+      ),
     ]);
   cache.set(name, mod);
   return mod;

package/src/output.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { BuildError, isInside, retryFs, copyDir } from './util.js';
+import { L } from './i18n.js';
 
 export const MANIFEST = '.builder-manifest.json';
 
@@ -12,18 +13,40 @@ export function assertSafeOutDir(cfg, { force = false } = {}) {
   const root = path.resolve(cfg.root);
   const parsed = path.parse(out);
   const same = (a, b) => path.relative(a, b) === '';
-  if (same(out, root)) throw new BuildError('"outDir" no puede ser la propia carpeta del proyecto: se borraría el código fuente.');
-  if (isInside(out, root)) throw new BuildError(`"outDir" (${out}) contiene al proyecto; se borraría el código fuente.`);
-  if (same(out, parsed.root)) throw new BuildError('"outDir" no puede ser la raíz de una unidad.');
-  if (same(out, os.homedir())) throw new BuildError('"outDir" no puede ser tu carpeta de usuario.');
+  if (same(out, root))
+    throw new BuildError(
+      L(
+        '"outDir" no puede ser la propia carpeta del proyecto: se borraría el código fuente.',
+        '"outDir" cannot be the project folder itself: the source code would be deleted.',
+      ),
+    );
+  if (isInside(out, root))
+    throw new BuildError(
+      L(
+        `"outDir" (${out}) contiene al proyecto; se borraría el código fuente.`,
+        `"outDir" (${out}) contains the project; the source code would be deleted.`,
+      ),
+    );
+  if (same(out, parsed.root)) throw new BuildError(L('"outDir" no puede ser la raíz de una unidad.', '"outDir" cannot be the root of a drive.'));
+  if (same(out, os.homedir())) throw new BuildError(L('"outDir" no puede ser tu carpeta de usuario.', '"outDir" cannot be your home folder.'));
   if (!cfg.clean || force) return;
   if (fs.existsSync(out)) {
-    if (!fs.statSync(out).isDirectory()) throw new BuildError(`"outDir" existe y no es una carpeta: ${out}`);
+    if (!fs.statSync(out).isDirectory())
+      throw new BuildError(L(`"outDir" existe y no es una carpeta: ${out}`, `"outDir" exists and is not a folder: ${out}`));
     const entries = fs.readdirSync(out);
     if (entries.length && !entries.includes(MANIFEST))
-      throw new BuildError(`La carpeta de salida ${out} ya tiene archivos y no la creó Builder. No la borro para no perder datos.`, [
-        'Elige otra carpeta con --out, vacíala tú mismo o usa --force si estás seguro.',
-      ]);
+      throw new BuildError(
+        L(
+          `La carpeta de salida ${out} ya tiene archivos y no la creó Builder. No la borro para no perder datos.`,
+          `The output folder ${out} already has files and was not created by Builder. Not deleting it, to avoid losing data.`,
+        ),
+        [
+          L(
+            'Elige otra carpeta con --out, vacíala tú mismo o usa --force si estás seguro.',
+            'Choose another folder with --out, empty it yourself, or use --force if you are sure.',
+          ),
+        ],
+      );
   }
 }
 
@@ -89,7 +112,12 @@ export async function swapIntoPlace(cfg, staging) {
       await rmrf(staging);
     } catch (copyErr) {
       if (exists) await retryFs(() => fs.promises.rename(old, out)).catch(() => {});
-      throw new BuildError(`No pude colocar la salida en ${out}: ${copyErr.message ?? err.message}`);
+      throw new BuildError(
+        L(
+          `No pude colocar la salida en ${out}: ${copyErr.message ?? err.message}`,
+          `Could not place the output in ${out}: ${copyErr.message ?? err.message}`,
+        ),
+      );
     }
   }
   if (exists) await rmrf(old).catch(() => {});

package/src/plugins.js

@@ -0,0 +1,126 @@
+// Plugins: ganchos sencillos para casos que Builder no cubre.
+//
+//   export default {
+//     plugins: [
+//       {
+//         name: 'version',
+//         filter: /\.(html|js)$/,                                  // opcional: a qué archivos se aplica transform
+//         transform: ({ path, code }) => code.replaceAll('__VERSION__', '1.2.3'),
+//         buildStart: ({ config, mode }) => {},
+//         buildEnd: ({ result, outDir }) => {},
+//       },
+//     ],
+//   };
+//
+// En builder.config.json se nombran paquetes: "plugins": ["mi-plugin", ["otro-plugin", { "opcion": 1 }]].
+// Un paquete exporta el objeto plugin o una función (opciones) => plugin.
+//
+// transform cambia el CÓDIGO FUENTE (HTML, CSS, JS, TS) antes de procesarlo: así el hash, el SRI
+// y la verificación final se calculan sobre el resultado del plugin.
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { BuildError } from './util.js';
+import { L } from './i18n.js';
+
+export const TRANSFORM_EXT = new Set(['.html', '.htm', '.css', '.js', '.mjs', '.cjs', '.ts', '.mts', '.cts']);
+const HOOKS = ['transform', 'buildStart', 'buildEnd'];
+
+/** Errores de validación de la opción "plugins" (antes de cargar paquetes). */
+export function validatePlugins(list) {
+  if (!Array.isArray(list)) return [L('"plugins" debe ser una lista.', '"plugins" must be a list.')];
+  const errors = [];
+  list.forEach((p, i) => {
+    const ok =
+      typeof p === 'string' ||
+      (Array.isArray(p) && typeof p[0] === 'string' && p.length <= 2) ||
+      (p && typeof p === 'object' && !Array.isArray(p) && typeof p.name === 'string');
+    if (!ok)
+      errors.push(
+        L(
+          `"plugins[${i}]" debe ser un nombre de paquete, [nombre, opciones] o un objeto con "name".`,
+          `"plugins[${i}]" must be a package name, [name, options] or an object with "name".`,
+        ),
+      );
+    else if (p && typeof p === 'object' && !Array.isArray(p)) {
+      for (const k of Object.keys(p))
+        if (!['name', 'filter', ...HOOKS].includes(k))
+          errors.push(
+            L(
+              `"plugins[${i}].${k}" no es un gancho conocido (${HOOKS.join(', ')}).`,
+              `"plugins[${i}].${k}" is not a known hook (${HOOKS.join(', ')}).`,
+            ),
+          );
+    }
+  });
+  return errors;
+}
+
+/** Carga los plugins nombrados como paquete (desde el proyecto) y devuelve objetos plugin. */
+export async function loadPlugins(list, root) {
+  const out = [];
+  for (const entry of list) {
+    if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+      out.push(entry);
+      continue;
+    }
+    const [name, options] = Array.isArray(entry) ? entry : [entry, undefined];
+    let mod;
+    try {
+      const req = createRequire(path.join(root, 'package.json'));
+      mod = await import(pathToFileURL(req.resolve(name)).href);
+    } catch (err) {
+      throw new BuildError(L(`No se pudo cargar el plugin "${name}": ${err.message}`, `Could not load the plugin "${name}": ${err.message}`), [
+        L(`Instálalo en el proyecto: npm install --save-dev ${name}`, `Install it in the project: npm install --save-dev ${name}`),
+      ]);
+    }
+    const exported = mod.default ?? mod;
+    const plugin = typeof exported === 'function' ? await exported(options ?? {}) : exported;
+    if (!plugin || typeof plugin !== 'object' || typeof plugin.name !== 'string')
+      throw new BuildError(
+        L(
+          `El plugin "${name}" debe exportar un objeto con "name" o una función que lo devuelva.`,
+          `The plugin "${name}" must export an object with "name" or a function that returns one.`,
+        ),
+      );
+    out.push(plugin);
+  }
+  return out;
+}
+
+async function call(plugin, hook, arg, where = '') {
+  try {
+    return await plugin[hook](arg);
+  } catch (err) {
+    throw new BuildError(
+      L(
+        `El plugin "${plugin.name}" falló en ${hook}${where}: ${err.message}`,
+        `The plugin "${plugin.name}" failed in ${hook}${where}: ${err.message}`,
+      ),
+    );
+  }
+}
+
+/** Ejecuta un gancho sin valor de retorno (buildStart, buildEnd) en todos los plugins, en orden. */
+export async function runHook(plugins, hook, arg) {
+  for (const p of plugins) if (typeof p[hook] === 'function') await call(p, hook, arg);
+}
+
+/** Pasa el código de un archivo por los transform de todos los plugins, en orden. */
+export async function runTransform(plugins, rel, code) {
+  let current = code;
+  for (const p of plugins) {
+    if (typeof p.transform !== 'function') continue;
+    if (p.filter instanceof RegExp && !p.filter.test(rel)) continue;
+    const r = await call(p, 'transform', { path: rel, code: current }, ` (${rel})`);
+    if (typeof r === 'string') current = r;
+    else if (r != null)
+      throw new BuildError(
+        L(
+          `El plugin "${p.name}" devolvió algo que no es texto en transform (${rel}).`,
+          `The plugin "${p.name}" returned something that is not text from transform (${rel}).`,
+        ),
+      );
+  }
+  return current;
+}