@rettangoli/fe 1.1.3 → 1.2.0

package/README.md

@@ -26,6 +26,7 @@ rtgl fe watch     # Start dev server
 - **[Schema System](./docs/schema.md)** - Component API and metadata
 - **[Store Management](./docs/store.md)** - State patterns
 - **[Event Handlers](./docs/handlers.md)** - Event handling
+- **[Internationalization](./docs/i18n.md)** - Locale files, view usage, and locale switching
 
 ## Architecture
 
@@ -123,6 +124,13 @@ fe:
     - "./src/pages"
   setup: "setup.js"
   outfile: "./dist/bundle.js"
+  i18n:
+    dir: "./src/i18n"
+    defaultLocale: "en"
+    fallbackLocale: "en"
+    locales:
+      - "en"
+      - "vi"
   examples:
     outputDir: "./vt/specs/examples"
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/fe",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Frontend framework for building reactive web components",
   "type": "module",
   "main": "./src/index.js",

package/src/cli/build.js

@@ -6,6 +6,7 @@ import {
   RETTANGOLI_FE_VIRTUAL_ENTRY_ID,
   createRettangoliFeVitePlugin,
 } from "./vitePlugin.js";
+import { emitI18nAssets, loadI18nBuildContext } from "./i18nBuild.js";
 
 const buildRettangoliFrontend = async (options = {}) => {
   console.log("running build with options", options);
@@ -16,12 +17,18 @@ const buildRettangoliFrontend = async (options = {}) => {
     outfile = "./vt/static/main.js",
     setup = "setup.js",
     development = false,
+    i18n = null,
   } = options;
 
   const resolvedOutfile = path.resolve(cwd, outfile);
   const outDir = path.dirname(resolvedOutfile);
   const outFileName = path.basename(resolvedOutfile);
   const relativeOutDir = path.relative(cwd, outDir) || ".";
+  const i18nContext = loadI18nBuildContext({
+    cwd,
+    i18n,
+    errorPrefix: "[Build]",
+  });
 
   await viteBuild({
     configFile: false,
@@ -31,6 +38,7 @@ const buildRettangoliFrontend = async (options = {}) => {
         cwd,
         dirs,
         setup,
+        i18n,
         errorPrefix: "[Build]",
       }),
     ],
@@ -52,6 +60,8 @@ const buildRettangoliFrontend = async (options = {}) => {
     },
   });
 
+  emitI18nAssets({ outDir, i18nContext });
+
   console.log(`Build complete. Output file: ${resolvedOutfile}`);
 };
 

package/src/cli/check.js

@@ -9,11 +9,16 @@ const checkRettangoliFrontend = (options = {}) => {
     cwd = process.cwd(),
     dirs = ["./example"],
     format = "text",
+    i18n = null,
   } = options;
   const outputFormat = format === "json" ? "json" : "text";
 
   const resolvedDirs = dirs.map((dir) => path.resolve(cwd, dir));
-  const { errors, summary, index } = analyzeComponentDirs({ dirs: resolvedDirs });
+  const { errors, summary, index } = analyzeComponentDirs({
+    dirs: resolvedDirs,
+    cwd,
+    i18n,
+  });
 
   if (errors.length > 0) {
     if (outputFormat === "json") {

package/src/cli/contracts.js

@@ -6,6 +6,7 @@ import {
   formatContractErrors as formatContractErrorLines,
   validateComponentContractIndex,
 } from "../core/contracts/componentFiles.js";
+import { analyzeI18nBuildContext } from "./i18nBuild.js";
 
 export const SUPPORTED_COMPONENT_FILE_SUFFIXES = Object.freeze([
   ".store.js",
@@ -54,9 +55,10 @@ export const collectComponentContractEntriesFromDirs = (dirs = []) => {
 export const validateComponentEntries = ({
   entries = [],
   errorPrefix = "[Check]",
+  i18nContext = { enabled: false },
 }) => {
   const index = buildComponentContractIndex(entries);
-  const errors = validateComponentContractIndex(index);
+  const errors = validateComponentContractIndex(index, { i18nContext });
   if (errors.length > 0) {
     throw new Error(
       `${errorPrefix} Component contract validation failed:\n${formatContractErrorLines(errors).join("\n")}`,
@@ -71,9 +73,14 @@ export const validateComponentEntries = ({
 export const validateComponentDirs = ({
   dirs = [],
   errorPrefix = "[Check]",
+  i18nContext = { enabled: false },
 }) => {
   const entries = collectComponentContractEntriesFromDirs(dirs);
-  const validationResult = validateComponentEntries({ entries, errorPrefix });
+  const validationResult = validateComponentEntries({
+    entries,
+    errorPrefix,
+    i18nContext,
+  });
   return {
     entries,
     ...validationResult,
@@ -131,9 +138,16 @@ export const formatContractFailureReport = ({
   ].join("\n");
 };
 
-export const analyzeComponentEntries = ({ entries = [] }) => {
+export const analyzeComponentEntries = ({
+  entries = [],
+  i18nContext = { enabled: false },
+  i18nErrors = [],
+}) => {
   const index = buildComponentContractIndex(entries);
-  const errors = validateComponentContractIndex(index);
+  const errors = [
+    ...i18nErrors,
+    ...validateComponentContractIndex(index, { i18nContext }),
+  ];
   const summary = summarizeContractErrors(errors);
   return {
     entries,
@@ -143,7 +157,19 @@ export const analyzeComponentEntries = ({ entries = [] }) => {
   };
 };
 
-export const analyzeComponentDirs = ({ dirs = [] }) => {
+export const analyzeComponentDirs = ({
+  dirs = [],
+  cwd = process.cwd(),
+  i18n = null,
+}) => {
   const entries = collectComponentContractEntriesFromDirs(dirs);
-  return analyzeComponentEntries({ entries });
+  const { context: i18nContext, errors: i18nErrors } = analyzeI18nBuildContext({
+    cwd,
+    i18n,
+  });
+  return analyzeComponentEntries({
+    entries,
+    i18nContext,
+    i18nErrors,
+  });
 };

package/src/cli/frontendEntrySource.js

@@ -9,6 +9,10 @@ import {
   isSupportedComponentFile,
   validateComponentEntries,
 } from "./contracts.js";
+import {
+  buildI18nAssets,
+  loadI18nBuildContext,
+} from "./i18nBuild.js";
 
 const MODULE_FILE_TYPES = new Set(["handlers", "store", "methods"]);
 const YAML_FILE_TYPES = new Set(["view", "constants", "schema"]);
@@ -65,15 +69,52 @@ const createComponentImportLines = ({ componentMatrix, categories }) => {
   return lines.join("\n");
 };
 
+const createI18nRuntimeSource = ({ i18nContext }) => {
+  if (!i18nContext.enabled) {
+    return "const __rtglFrameworkDeps = {};";
+  }
+
+  const assets = buildI18nAssets({ i18nContext });
+  const urlEntries = assets
+    .map((asset) => {
+      return `  ${JSON.stringify(asset.locale)}: new URL(/* @vite-ignore */ ${JSON.stringify(`./${asset.relativeFileName}`)}, import.meta.url).href,`;
+    })
+    .join("\n");
+
+  const initialCatalogs = {};
+  initialCatalogs[i18nContext.defaultLocale] =
+    i18nContext.catalogs[i18nContext.defaultLocale];
+  initialCatalogs[i18nContext.fallbackLocale] =
+    i18nContext.catalogs[i18nContext.fallbackLocale];
+
+  return `
+const __rtglI18nRuntime = createI18nRuntime({
+  defaultLocale: ${JSON.stringify(i18nContext.defaultLocale)},
+  fallbackLocale: ${JSON.stringify(i18nContext.fallbackLocale)},
+  locales: ${JSON.stringify(i18nContext.locales)},
+  urls: {
+${urlEntries}
+  },
+  initialCatalogs: ${JSON.stringify(initialCatalogs)},
+});
+await __rtglI18nRuntime.ready();
+const __rtglFrameworkDeps = {
+  __rtglI18nRuntime,
+  locale: __rtglI18nRuntime.locale,
+};`.trim();
+};
+
 export const generateFrontendEntrySource = ({
   cwd = process.cwd(),
   dirs = ["./example"],
   setup = "setup.js",
   command = "build",
+  i18n = null,
   errorPrefix = "[Build]",
 } = {}) => {
   const resolvedDirs = dirs.map((dir) => path.resolve(cwd, dir));
   const resolvedSetup = path.resolve(cwd, setup);
+  const i18nContext = loadI18nBuildContext({ cwd, i18n, errorPrefix });
   const allFiles = getAllFiles(resolvedDirs)
     .filter((filePath) => isSupportedComponentFile(filePath))
     .sort((a, b) => a.localeCompare(b));
@@ -143,6 +184,7 @@ export const generateFrontendEntrySource = ({
   validateComponentEntries({
     entries: componentContractEntries,
     errorPrefix,
+    i18nContext,
   });
 
   const setupImportPath = toImportPath({
@@ -153,18 +195,28 @@ export const generateFrontendEntrySource = ({
     componentMatrix,
     categories: Object.keys(componentMatrix).sort(),
   });
+  const feImports = i18nContext.enabled
+    ? "createComponent, createI18nRuntime"
+    : "createComponent";
+  const i18nRuntimeSource = createI18nRuntimeSource({ i18nContext });
 
   return `
 ${declarationLines.join("\n")}
-import { createComponent } from "@rettangoli/fe";
+import { ${feImports} } from "@rettangoli/fe";
 import { deps } from ${JSON.stringify(setupImportPath)};
 
 ${categoryLines}
 
+${i18nRuntimeSource}
+
 Object.keys(imports).forEach((category) => {
   Object.keys(imports[category]).forEach((component) => {
     const componentConfig = imports[category][component];
-    const webComponent = createComponent({ ...componentConfig }, deps[category]);
+    const categoryDeps = {
+      ...((deps && deps[category]) || {}),
+      ...__rtglFrameworkDeps,
+    };
+    const webComponent = createComponent({ ...componentConfig }, categoryDeps);
     const elementName = componentConfig.schema?.componentName;
     if (!elementName) {
       throw new Error(

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),
+  );
+};