@rettangoli/fe 1.1.3 → 1.2.1

package/src/cli/i18nBuild.js

@@ -0,0 +1,367 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+
+import { load as loadYaml } from "js-yaml";
+
+const DEFAULT_OUTPUT_DIR = "i18n";
+const LOCALE_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const toPosixPath = (value) => value.split(path.sep).join("/");
+
+const createI18nError = ({ code = "RTGL-I18N-004", message, filePath }) => ({
+  code,
+  message,
+  filePath: filePath || "",
+});
+
+const assertNoI18nErrors = ({ errors, errorPrefix }) => {
+  if (errors.length === 0) {
+    return;
+  }
+
+  const details = errors
+    .map((error) => `${error.code} ${error.message}${error.filePath ? ` [${error.filePath}]` : ""}`)
+    .join("\n");
+  throw new Error(`${errorPrefix} i18n validation failed:\n${details}`);
+};
+
+const validateLocaleName = ({ locale, errors, filePath }) => {
+  if (typeof locale !== "string" || !LOCALE_PATTERN.test(locale)) {
+    errors.push(createI18nError({
+      message: `invalid locale name ${JSON.stringify(locale)}. Locale names may contain letters, numbers, "_" and "-".`,
+      filePath,
+    }));
+    return false;
+  }
+  return true;
+};
+
+const flattenCatalogKeys = (catalog = {}) => {
+  const keys = [];
+  Object.entries(catalog).forEach(([namespace, messages]) => {
+    Object.keys(messages || {}).forEach((key) => {
+      keys.push(`${namespace}.${key}`);
+    });
+  });
+  return keys.sort();
+};
+
+const validateCatalog = ({ catalog, locale, filePath }) => {
+  const errors = [];
+  const normalized = {};
+
+  if (!isPlainObject(catalog)) {
+    errors.push(createI18nError({
+      message: `${locale}.yaml must contain a YAML object at the root.`,
+      filePath,
+    }));
+    return { catalog: normalized, errors };
+  }
+
+  Object.entries(catalog).forEach(([namespace, messages]) => {
+    if (!isPlainObject(messages)) {
+      errors.push(createI18nError({
+        message: `${locale}.yaml namespace "${namespace}" must be an object. Use namespace -> key -> content.`,
+        filePath,
+      }));
+      return;
+    }
+
+    normalized[namespace] = {};
+    Object.entries(messages).forEach(([key, content]) => {
+      if (isPlainObject(content) || Array.isArray(content)) {
+        errors.push(createI18nError({
+          message: `${locale}.yaml key "${namespace}.${key}" is nested too deeply. Use namespace -> key -> content only.`,
+          filePath,
+        }));
+        return;
+      }
+
+      if (typeof content !== "string") {
+        errors.push(createI18nError({
+          message: `${locale}.yaml key "${namespace}.${key}" must be a string.`,
+          filePath,
+        }));
+        return;
+      }
+
+      normalized[namespace][key] = content;
+    });
+  });
+
+  return { catalog: normalized, errors };
+};
+
+const normalizeI18nConfig = ({ cwd, i18n }) => {
+  const errors = [];
+
+  if (!i18n) {
+    return {
+      config: { enabled: false },
+      errors,
+    };
+  }
+
+  if (!isPlainObject(i18n)) {
+    errors.push(createI18nError({
+      message: "fe.i18n must be an object.",
+    }));
+    return {
+      config: { enabled: false },
+      errors,
+    };
+  }
+
+  const dir = i18n.dir;
+  if (typeof dir !== "string" || dir.trim() === "") {
+    errors.push(createI18nError({
+      message: "fe.i18n.dir must be a non-empty string.",
+    }));
+  }
+
+  const defaultLocale = i18n.defaultLocale;
+  const fallbackLocale = i18n.fallbackLocale;
+  validateLocaleName({ locale: defaultLocale, errors });
+  validateLocaleName({ locale: fallbackLocale, errors });
+
+  if (!Array.isArray(i18n.locales) || i18n.locales.length === 0) {
+    errors.push(createI18nError({
+      message: "fe.i18n.locales must be a non-empty array.",
+    }));
+  }
+
+  const locales = [];
+  const seen = new Set();
+  if (Array.isArray(i18n.locales)) {
+    i18n.locales.forEach((locale) => {
+      if (!validateLocaleName({ locale, errors })) {
+        return;
+      }
+      if (seen.has(locale)) {
+        errors.push(createI18nError({
+          message: `fe.i18n.locales contains duplicate locale "${locale}".`,
+        }));
+        return;
+      }
+      seen.add(locale);
+      locales.push(locale);
+    });
+  }
+
+  if (defaultLocale && locales.length > 0 && !seen.has(defaultLocale)) {
+    errors.push(createI18nError({
+      message: `fe.i18n.defaultLocale "${defaultLocale}" must be listed in fe.i18n.locales.`,
+    }));
+  }
+
+  if (fallbackLocale && locales.length > 0 && !seen.has(fallbackLocale)) {
+    errors.push(createI18nError({
+      message: `fe.i18n.fallbackLocale "${fallbackLocale}" must be listed in fe.i18n.locales.`,
+    }));
+  }
+
+  const outputDir = typeof i18n.outputDir === "string" && i18n.outputDir.trim()
+    ? i18n.outputDir
+    : DEFAULT_OUTPUT_DIR;
+  const normalizedOutputDir = outputDir.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+  if (
+    !normalizedOutputDir ||
+    normalizedOutputDir.split("/").includes("..") ||
+    path.posix.isAbsolute(normalizedOutputDir)
+  ) {
+    errors.push(createI18nError({
+      message: "fe.i18n.outputDir must be a relative path when provided.",
+    }));
+  }
+
+  return {
+    config: {
+      enabled: errors.length === 0,
+      dir,
+      resolvedDir: dir ? path.resolve(cwd, dir) : null,
+      outputDir: normalizedOutputDir || DEFAULT_OUTPUT_DIR,
+      defaultLocale,
+      fallbackLocale,
+      locales,
+    },
+    errors,
+  };
+};
+
+export const analyzeI18nBuildContext = ({
+  cwd = process.cwd(),
+  i18n = null,
+} = {}) => {
+  const { config, errors } = normalizeI18nConfig({ cwd, i18n });
+
+  if (!i18n || errors.length > 0) {
+    return {
+      context: { enabled: false },
+      errors,
+    };
+  }
+
+  if (!existsSync(config.resolvedDir)) {
+    errors.push(createI18nError({
+      message: `fe.i18n.dir does not exist: ${config.resolvedDir}`,
+      filePath: config.resolvedDir,
+    }));
+    return {
+      context: { enabled: false },
+      errors,
+    };
+  }
+
+  const localeFiles = {};
+  const catalogs = {};
+
+  config.locales.forEach((locale) => {
+    const filePath = path.join(config.resolvedDir, `${locale}.yaml`);
+    localeFiles[locale] = filePath;
+
+    if (!existsSync(filePath)) {
+      errors.push(createI18nError({
+        message: `missing i18n file for locale "${locale}". Expected ${filePath}.`,
+        filePath,
+      }));
+      return;
+    }
+
+    let yamlObject;
+    try {
+      yamlObject = loadYaml(readFileSync(filePath, "utf8")) ?? {};
+    } catch (error) {
+      errors.push(createI18nError({
+        message: `failed to parse ${locale}.yaml: ${error.message}`,
+        filePath,
+      }));
+      return;
+    }
+
+    const result = validateCatalog({ catalog: yamlObject, locale, filePath });
+    errors.push(...result.errors);
+    catalogs[locale] = result.catalog;
+  });
+
+  const defaultCatalog = catalogs[config.defaultLocale];
+  if (defaultCatalog) {
+    const defaultKeys = flattenCatalogKeys(defaultCatalog);
+    config.locales.forEach((locale) => {
+      if (locale === config.defaultLocale || !catalogs[locale]) {
+        return;
+      }
+
+      defaultKeys.forEach((fullKey) => {
+        const [namespace, key] = fullKey.split(".");
+        if (
+          !Object.prototype.hasOwnProperty.call(catalogs[locale] || {}, namespace) ||
+          !Object.prototype.hasOwnProperty.call(catalogs[locale]?.[namespace] || {}, key)
+        ) {
+          errors.push(createI18nError({
+            message: `${locale}.yaml is missing key "${fullKey}" from default locale "${config.defaultLocale}".`,
+            filePath: localeFiles[locale],
+          }));
+        }
+      });
+    });
+  }
+
+  const context = {
+    ...config,
+    enabled: errors.length === 0,
+    localeFiles,
+    catalogs,
+  };
+
+  return {
+    context,
+    errors,
+  };
+};
+
+export const loadI18nBuildContext = ({
+  cwd = process.cwd(),
+  i18n = null,
+  errorPrefix = "[Build]",
+} = {}) => {
+  const { context, errors } = analyzeI18nBuildContext({ cwd, i18n });
+  assertNoI18nErrors({ errors, errorPrefix });
+  return context;
+};
+
+export const buildI18nAssets = ({ i18nContext }) => {
+  if (!i18nContext?.enabled) {
+    return [];
+  }
+
+  return i18nContext.locales.map((locale) => {
+    const relativeFileName = path.posix.join(
+      i18nContext.outputDir,
+      `${locale}.json`,
+    );
+    return {
+      locale,
+      relativeFileName,
+      sourcePath: i18nContext.localeFiles[locale],
+      catalog: i18nContext.catalogs[locale],
+      content: `${JSON.stringify(i18nContext.catalogs[locale], null, 2)}\n`,
+    };
+  });
+};
+
+export const emitI18nAssets = ({ outDir, i18nContext }) => {
+  const assets = buildI18nAssets({ i18nContext });
+
+  return assets.map((asset) => {
+    const outputPath = path.resolve(outDir, asset.relativeFileName);
+    mkdirSync(path.dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, asset.content);
+    return {
+      ...asset,
+      outputPath,
+    };
+  });
+};
+
+export const isI18nSourceFilePath = ({ filePath, i18nContext }) => {
+  if (!i18nContext?.enabled && !i18nContext?.resolvedDir) {
+    return false;
+  }
+
+  const resolvedFilePath = path.resolve(filePath);
+  const extension = path.extname(resolvedFilePath);
+  if (extension !== ".yaml") {
+    return false;
+  }
+
+  const relativePath = path.relative(i18nContext.resolvedDir, resolvedFilePath);
+  return (
+    relativePath !== "" &&
+    !relativePath.startsWith("..") &&
+    !path.isAbsolute(relativePath)
+  );
+};
+
+export const getI18nPublicAssetPath = ({
+  publicEntryPath,
+  relativeFileName,
+}) => {
+  const normalizedEntry = publicEntryPath
+    ? publicEntryPath.replace(/\\/g, "/")
+    : "/main.js";
+  const entryPath = normalizedEntry.startsWith("/")
+    ? normalizedEntry
+    : `/${normalizedEntry}`;
+  return path.posix.join(
+    path.posix.dirname(entryPath),
+    toPosixPath(relativeFileName),
+  );
+};

package/src/cli/vitePlugin.js

@@ -1,7 +1,14 @@
 import path from "node:path";
 
+import { getAllFiles } from "../commonBuild.js";
 import { isSupportedComponentFile } from "./contracts.js";
 import { generateFrontendEntrySource } from "./frontendEntrySource.js";
+import {
+  buildI18nAssets,
+  getI18nPublicAssetPath,
+  isI18nSourceFilePath,
+  loadI18nBuildContext,
+} from "./i18nBuild.js";
 
 export const RETTANGOLI_FE_VIRTUAL_ENTRY_ID = "virtual:rettangoli-fe-entry";
 const RESOLVED_VIRTUAL_ENTRY_ID = `\0${RETTANGOLI_FE_VIRTUAL_ENTRY_ID}`;
@@ -22,26 +29,61 @@ const normalizePublicEntryPath = (value) => {
   return normalized.startsWith("/") ? normalized : `/${normalized}`;
 };
 
+const getI18nWatchPaths = ({ i18nContext }) => {
+  if (!i18nContext?.enabled) {
+    return [];
+  }
+
+  return [
+    i18nContext.resolvedDir,
+    ...Object.values(i18nContext.localeFiles || {}),
+  ].filter(Boolean);
+};
+
 export const createRettangoliFeVitePlugin = ({
   cwd = process.cwd(),
   dirs = ["./example"],
   setup = "setup.js",
+  i18n = null,
   errorPrefix = "[Build]",
   publicEntryPath = null,
 } = {}) => {
   const resolvedDirs = dirs.map((directory) => path.resolve(cwd, directory));
   const resolvedSetup = path.resolve(cwd, setup);
   const normalizedPublicEntryPath = normalizePublicEntryPath(publicEntryPath);
+  const i18nContext = loadI18nBuildContext({ cwd, i18n, errorPrefix });
 
   let currentCommand = "build";
   let devServer = null;
 
+  const getComponentFilePaths = () => {
+    return getAllFiles(resolvedDirs)
+      .filter((filePath) => isSupportedComponentFile(filePath));
+  };
+
+  const getEntryWatchPaths = ({ includeDirectories = false } = {}) => {
+    const i18nWatchPaths = includeDirectories
+      ? getI18nWatchPaths({ i18nContext })
+      : Object.values(i18nContext.localeFiles || {});
+
+    return [
+      ...(includeDirectories ? resolvedDirs : []),
+      resolvedSetup,
+      ...getComponentFilePaths(),
+      ...i18nWatchPaths,
+    ];
+  };
+
   const isTrackedFilePath = (value) => {
     const filePath = path.resolve(value);
     if (filePath === resolvedSetup) {
       return true;
     }
 
+    if (isI18nSourceFilePath({ filePath, i18nContext })) {
+      return true;
+    }
+
     if (!isSupportedComponentFile(filePath)) {
       return false;
     }
@@ -87,16 +129,64 @@ export const createRettangoliFeVitePlugin = ({
       if (id !== RESOLVED_VIRTUAL_ENTRY_ID) {
         return null;
       }
+
+      for (const filePath of getEntryWatchPaths()) {
+        if (typeof this.addWatchFile === "function") {
+          this.addWatchFile(filePath);
+        }
+      }
+
       return generateFrontendEntrySource({
         cwd,
         dirs,
         setup,
+        i18n,
         command: currentCommand,
         errorPrefix,
       });
     },
     configureServer(server) {
       devServer = server;
+      server.watcher.add(getEntryWatchPaths({ includeDirectories: true }));
+
+      const serveI18nAsset = (req, res, next) => {
+        if (!i18nContext.enabled || !normalizedPublicEntryPath) {
+          next();
+          return;
+        }
+
+        const reqPath = (req.url || "").split("?")[0];
+
+        try {
+          const currentI18nContext = loadI18nBuildContext({
+            cwd,
+            i18n,
+            errorPrefix,
+          });
+          const asset = buildI18nAssets({
+            i18nContext: currentI18nContext,
+          }).find((candidate) => {
+            const publicPath = getI18nPublicAssetPath({
+              publicEntryPath: normalizedPublicEntryPath,
+              relativeFileName: candidate.relativeFileName,
+            });
+            return reqPath === publicPath;
+          });
+
+          if (!asset) {
+            next();
+            return;
+          }
+
+          res.statusCode = 200;
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.end(asset.content);
+        } catch (error) {
+          res.statusCode = 500;
+          res.setHeader("Content-Type", "text/plain; charset=utf-8");
+          res.end(error.stack || String(error));
+        }
+      };
 
       const onAdd = (filePath) => {
         if (isTrackedFilePath(filePath)) {
@@ -114,6 +204,7 @@ export const createRettangoliFeVitePlugin = ({
       server.watcher.on("unlink", onUnlink);
 
       if (normalizedPublicEntryPath) {
+        server.middlewares.use(serveI18nAsset);
         server.middlewares.use(async (req, res, next) => {
           const reqPath = (req.url || "").split("?")[0];
           if (reqPath !== normalizedPublicEntryPath) {

package/src/cli/watch.js

@@ -2,7 +2,10 @@ import path from "node:path";
 
 import { createServer } from "vite";
 
-import { createRettangoliFeVitePlugin } from "./vitePlugin.js";
+import {
+  RETTANGOLI_FE_VIRTUAL_ENTRY_ID,
+  createRettangoliFeVitePlugin,
+} from "./vitePlugin.js";
 
 const toPosixPath = (value) => value.split(path.sep).join("/");
 
@@ -39,15 +42,18 @@ export const createWatchServer = async (options = {}) => {
     port = 3001,
     outfile = "./vt/static/main.js",
     setup = "setup.js",
+    i18n = null,
   } = options;
 
   const { root, publicEntryPath } = resolveServeContext({ cwd, outfile });
 
   const server = await createServer({
+    clearScreen: false,
     configFile: false,
     root,
     server: {
       port,
+      strictPort: true,
       host: "0.0.0.0",
       allowedHosts: true,
     },
@@ -56,6 +62,7 @@ export const createWatchServer = async (options = {}) => {
         cwd,
         dirs,
         setup,
+        i18n,
         errorPrefix: "[Watch]",
         publicEntryPath,
       }),
@@ -73,12 +80,13 @@ const startWatching = async (options = {}) => {
   } = options;
   const { root, publicEntryPath } = resolveServeContext({ cwd, outfile });
 
-  console.log("watch root dir:", root);
-  console.log("watch entry path:", publicEntryPath);
+  console.log(`[Watch] Root: ${root}`);
+  console.log(`[Watch] Entry: ${publicEntryPath}`);
 
   try {
     const server = await createWatchServer(options);
     await server.listen();
+    await server.transformRequest(RETTANGOLI_FE_VIRTUAL_ENTRY_ID);
     server.printUrls();
     if (enableCliShortcuts) {
       server.bindCLIShortcuts({ print: true });

package/src/core/contracts/componentFiles.js

@@ -1,4 +1,5 @@
 import { findUnsupportedTemplatePropertyBindingSyntax } from "../view/templatePropertyBindings.js";
+import { validateViewI18nReferences } from "../i18n/viewReferences.js";
 
 export const FORBIDDEN_VIEW_KEYS = Object.freeze([
   "elementName",
@@ -51,7 +52,8 @@ export const buildComponentContractIndex = (entries = []) => {
   return index;
 };
 
-export const validateComponentContractIndex = (index = {}) => {
+export const validateComponentContractIndex = (index = {}, options = {}) => {
+  const { i18nContext = { enabled: false } } = options;
   const errors = [];
 
   Object.entries(index).forEach(([category, components]) => {
@@ -90,6 +92,13 @@ export const validateComponentContractIndex = (index = {}) => {
           filePath: viewFilePath || representativeFile,
         });
       }
+
+      errors.push(...validateViewI18nReferences({
+        viewYaml,
+        componentLabel,
+        filePath: viewFilePath || representativeFile,
+        i18nContext,
+      }));
     });
   });