@open-assets/open-assets 0.2.0 → 0.4.0

package/bin/open-assets.mjs

@@ -89,6 +89,7 @@ program
   .option("--tag <tag>", "Render only collections with this tag")
   .option("--template <name>", "Render only the template with this name")
   .option("--size <name>", "Use a named export size from config")
+  .option("--locale <code>", "Render only this locale (e.g. en, ar, ja)")
   .option("--width <px>", "Output width in pixels (custom size)")
   .option("--height <px>", "Output height in pixels (custom size)")
   .option("-f, --force", "Export at every size and re-render all assets (ignores cache)")

package/lib/localization.mjs

@@ -0,0 +1,159 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+
+/**
+ * Locales that use right-to-left script direction.
+ * Includes base language codes — region variants (e.g. "ar-SA") are
+ * detected by matching the base language.
+ */
+const RTL_LANGUAGES = new Set([
+  "ar",  // Arabic
+  "he",  // Hebrew
+  "fa",  // Persian (Farsi)
+  "ur",  // Urdu
+  "yi",  // Yiddish
+  "ps",  // Pashto
+  "sd",  // Sindhi
+  "ku",  // Kurdish (Sorani)
+  "dv",  // Divehi (Maldivian)
+  "ug",  // Uyghur
+]);
+
+/**
+ * Check if a locale uses right-to-left text direction.
+ * Matches exact locale codes and base language (e.g. "ar-SA" → "ar").
+ */
+export function isRtl(locale) {
+  if (RTL_LANGUAGES.has(locale)) return true;
+  const base = locale.split("-")[0];
+  return RTL_LANGUAGES.has(base);
+}
+
+/**
+ * Get text direction for a locale: "rtl" or "ltr".
+ */
+export function getDirection(locale) {
+  return isRtl(locale) ? "rtl" : "ltr";
+}
+
+/**
+ * Load and parse a localizations JSON file (iOS .xcstrings-inspired format).
+ *
+ * Expected format:
+ * {
+ *   "sourceLanguage": "en",
+ *   "strings": {
+ *     "key_name": {
+ *       "localizations": {
+ *         "en": { "value": "Hello" },
+ *         "ar": { "value": "مرحبا" }
+ *       }
+ *     }
+ *   }
+ * }
+ */
+export function loadLocalizations(projectDir, localizationsPath) {
+  const fullPath = resolve(projectDir, localizationsPath);
+  if (!existsSync(fullPath)) {
+    throw new Error(`Localizations file not found: ${localizationsPath}`);
+  }
+  try {
+    return JSON.parse(readFileSync(fullPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${localizationsPath}: ${err.message}`);
+  }
+}
+
+/**
+ * Resolve all localized string values for a given locale.
+ * Falls back: exact locale → base language → source language.
+ *
+ * Returns a flat { key: value } map.
+ */
+export function resolveStrings(localizations, locale) {
+  const strings = {};
+  const sourceLanguage = localizations.sourceLanguage || "en";
+
+  for (const [key, entry] of Object.entries(localizations.strings || {})) {
+    const l10ns = entry.localizations || {};
+    const value =
+      l10ns[locale]?.value ??
+      l10ns[locale.split("-")[0]]?.value ??
+      l10ns[sourceLanguage]?.value;
+    if (value !== undefined) {
+      strings[key] = value;
+    }
+  }
+
+  return strings;
+}
+
+/**
+ * Collect all unique locales defined across all string entries.
+ * If filterLocales is provided, returns only those that exist in the data.
+ * Results are sorted alphabetically.
+ */
+export function getLocales(localizations, filterLocales) {
+  const allLocales = new Set();
+  for (const entry of Object.values(localizations.strings || {})) {
+    for (const locale of Object.keys(entry.localizations || {})) {
+      allLocales.add(locale);
+    }
+  }
+
+  if (filterLocales && filterLocales.length > 0) {
+    return filterLocales.filter((l) => allLocales.has(l));
+  }
+
+  return [...allLocales].sort();
+}
+
+/**
+ * JavaScript snippet injected into the Puppeteer page to perform
+ * localization substitution on the live DOM.
+ *
+ * Replaces {{key}} placeholders in text nodes with localized values.
+ * Processes {{n:NUMBER}} patterns in values for locale-aware number formatting.
+ * Sets lang and dir attributes on <html>.
+ */
+export function buildLocalizationScript(strings, locale, direction) {
+  return `
+    (function() {
+      document.documentElement.lang = ${JSON.stringify(locale)};
+
+      const strings = ${JSON.stringify(strings)};
+      const locale = ${JSON.stringify(locale)};
+      const dir = ${JSON.stringify(direction)};
+      const formatter = new Intl.NumberFormat(locale);
+
+      function processValue(value) {
+        return value.replace(/\\{\\{n:(\\d+(?:\\.\\d+)?)\\}\\}/g, function(_, num) {
+          return formatter.format(parseFloat(num));
+        });
+      }
+
+      const walker = document.createTreeWalker(
+        document.documentElement,
+        NodeFilter.SHOW_TEXT
+      );
+      while (walker.nextNode()) {
+        var node = walker.currentNode;
+        var text = node.textContent;
+        var changed = false;
+        text = text.replace(/\\{\\{([a-zA-Z_][\\w.]*)\\}\\}/g, function(match, key) {
+          if (strings[key] !== undefined) {
+            changed = true;
+            return processValue(strings[key]);
+          }
+          return match;
+        });
+        if (changed) {
+          node.textContent = text;
+          if (dir === "rtl") {
+            node.parentElement.dir = dir;
+          }
+        }
+      }
+    })();
+  `;
+}

package/lib/lockfile.mjs

@@ -90,13 +90,14 @@ export function computeChecksum(filePath) {
 }
 
 /**
- * Check if an asset variant is up-to-date based on its stored checksum.
- * Returns true if the stored checksum matches and the output file exists.
+ * Check if an asset variant is up-to-date based on its stored checksums.
+ * Returns true if both source and export config checksums match and the output file exists.
  */
-export function isUpToDate(lockData, assetKey, variantKey, currentChecksum, outputPath) {
+export function isUpToDate(lockData, assetKey, variantKey, currentChecksum, outputPath, exportChecksum) {
   const entry = lockData.assets?.[assetKey]?.[variantKey];
   if (!entry) return false;
   if (entry.sourceChecksum !== currentChecksum) return false;
+  if (exportChecksum && entry.exportChecksum !== exportChecksum) return false;
   if (!existsSync(resolve(outputPath))) return false;
   return true;
 }
@@ -104,13 +105,36 @@ export function isUpToDate(lockData, assetKey, variantKey, currentChecksum, outp
 /**
  * Record an export in the lockfile data (in memory — call writeLockfile to persist).
  */
-export function recordExport(lockData, assetKey, variantKey, checksum, outputPath) {
+export function recordExport(lockData, assetKey, variantKey, checksum, outputPath, exportChecksum) {
   if (!lockData.assets[assetKey]) {
     lockData.assets[assetKey] = {};
   }
-  lockData.assets[assetKey][variantKey] = {
+  const entry = {
     sourceChecksum: checksum,
     outputPath,
     exportedAt: new Date().toISOString(),
   };
+  if (exportChecksum) {
+    entry.exportChecksum = exportChecksum;
+  }
+  lockData.assets[assetKey][variantKey] = entry;
+}
+
+/**
+ * Compute a checksum for the export configuration of a variant.
+ * Captures size dimensions, outFile path, and locale so that config changes trigger re-export.
+ */
+export function computeExportChecksum(entry, locale) {
+  const config = {
+    width: entry.size.width,
+    height: entry.size.height,
+  };
+  if (entry.outFile) {
+    config.outFile = entry.outFile;
+  }
+  if (locale) {
+    config.locale = locale;
+  }
+  const hash = createHash("sha256").update(JSON.stringify(config)).digest("hex");
+  return `sha256:${hash}`;
 }

package/lib/render.mjs

@@ -1,6 +1,8 @@
 import { resolve, join } from "path";
 import { mkdirSync, writeFileSync, copyFileSync, existsSync } from "fs";
 import { filterCollections, filterTemplates, resolveRenderSizes, flatOutputs } from "./manifest.mjs";
+import { computeExportChecksum } from "./lockfile.mjs";
+import { loadLocalizations, resolveStrings, getLocales, getDirection } from "./localization.mjs";
 
 /**
  * @typedef {object} RenderDeps
@@ -10,8 +12,8 @@ import { filterCollections, filterTemplates, resolveRenderSizes, flatOutputs } f
  * @property {(projectDir: string) => object} readLockfile
  * @property {(projectDir: string, data: object) => void} writeLockfile
  * @property {(filePath: string) => string|null} computeChecksum
- * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string) => boolean} isUpToDate
- * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string) => void} recordExport
+ * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string, exportChecksum?: string) => boolean} isUpToDate
+ * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string, exportChecksum?: string) => void} recordExport
  */
 
 /**
@@ -24,6 +26,7 @@ import { filterCollections, filterTemplates, resolveRenderSizes, flatOutputs } f
  * @param {string} [options.tag] - Filter by tag
  * @param {string} [options.template] - Filter by template name/label
  * @param {string} [options.size] - Named export size
+ * @param {string} [options.locale] - Filter to a single locale
  * @param {string} [options.format] - Output format override (png or jpg)
  * @param {string|number} [options.width] - Custom width
  * @param {string|number} [options.height] - Custom height
@@ -79,97 +82,144 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
       continue;
     }
 
+    // Resolve locales for this collection
+    let locales = [null]; // null = no localization
+    let localizations = null;
+
+    if (col.localizations) {
+      localizations = loadLocalizations(projectDir, col.localizations);
+      locales = getLocales(localizations, col.locales);
+      if (options.locale) {
+        locales = locales.filter((l) => l === options.locale);
+        if (locales.length === 0) {
+          _log(`  Warning: locale "${options.locale}" not found in collection "${col.id}", skipping`);
+          continue;
+        }
+      }
+    }
+
     const singleTemplate = templates.length === 1;
     const multipleSizes = sizesToRender.length > 1 || options.force;
     // Single-template collections use flat layout with entry.name as filename
     // Multi-template collections use subdirs per size
     const useSubDirs = multipleSizes && !singleTemplate;
+    const hasLocales = locales.length > 0 && locales[0] !== null;
 
-    for (const entry of sizesToRender) {
-      const w = entry.size.width;
-      const h = entry.size.height;
+    for (const locale of locales) {
+      const strings = locale ? resolveStrings(localizations, locale) : null;
+      const direction = locale ? getDirection(locale) : null;
+      const localization = locale ? { strings, locale, direction } : undefined;
 
-      const sizeDir = useSubDirs
-        ? join(outputDir, col.id, entry.name)
-        : join(outputDir, col.id);
-      mkdirSync(sizeDir, { recursive: true });
-
-      if (sizesToRender.length > 1) {
-        _log(`\n  ${entry.label} (${w}x${h})`);
+      if (locale) {
+        _log(`\n  Locale: ${locale} (${direction})`);
       }
 
-      for (const template of templates) {
-        // Determine output format from outFile extension or default to png
-        const outExt = entry.outFile
-          ? entry.outFile.split(".").pop().toLowerCase()
-          : "png";
-        const format = outExt === "jpg" || outExt === "jpeg" ? "jpeg" : "png";
-        const defaultExt = format === "jpeg" ? "jpg" : "png";
-
-        // Single-template: use entry.name as filename (e.g. logo-1024.png)
-        // Multi-template: use template.name as filename (e.g. 01-hero.png)
-        const fileName = singleTemplate && multipleSizes
-          ? `${entry.name}.${defaultExt}`
-          : `${template.name}.${defaultExt}`;
-
-        const outPath = entry.outFile
-          ? resolve(projectDir, entry.outFile.replace(/\{template\}/g, template.name))
-          : join(sizeDir, fileName);
-
-        const assetKey = `${col.id}/${template.name}`;
-        const variantKey = entry.name;
-        const srcPath = resolve(projectDir, template.src);
-        const checksum = deps.computeChecksum(srcPath);
-
-        // Skip if unchanged
-        if (
-          !options.force &&
-          checksum &&
-          deps.isUpToDate(lockData, assetKey, variantKey, checksum, outPath)
-        ) {
-          _log(
-            `  Skipping ${template.name} at ${w}x${h} (unchanged)`
-          );
-          skipped++;
-          continue;
-        }
-
-        _log(
-          `  Rendering ${template.name} at ${w}x${h}...`
-        );
+      for (const entry of sizesToRender) {
+        const w = entry.size.width;
+        const h = entry.size.height;
 
-        const isSvg = template.src.endsWith(".svg");
-        if (isSvg && w === sourceW && h === sourceH) {
-          copyFileSync(srcPath, outPath.replace(`.${defaultExt}`, ".svg"));
+        // Build output directory: insert locale level when localizations are active
+        let sizeDir;
+        if (hasLocales) {
+          sizeDir = useSubDirs
+            ? join(outputDir, col.id, locale, entry.name)
+            : join(outputDir, col.id, locale);
+        } else {
+          sizeDir = useSubDirs
+            ? join(outputDir, col.id, entry.name)
+            : join(outputDir, col.id);
         }
+        mkdirSync(sizeDir, { recursive: true });
 
-        // Ensure output directory exists when using outFile
-        if (entry.outFile) {
-          mkdirSync(resolve(projectDir, join(outPath, "..")), { recursive: true });
+        if (sizesToRender.length > 1) {
+          _log(`\n  ${entry.label} (${w}x${h})`);
         }
 
-        const buffer = await deps.renderScreenshot(
-          projectDir,
-          template.src,
-          w,
-          h,
-          sourceW,
-          sourceH,
-          { format, background: col.background }
-        );
-        writeFileSync(outPath, buffer);
-        results.push({
-          collection: col.id,
-          template: template.name,
-          path: outPath,
-          width: w,
-          height: h,
-          size: buffer.length,
-        });
-        if (checksum) {
-          deps.recordExport(lockData, assetKey, variantKey, checksum, outPath);
+        for (const template of templates) {
+          // Determine output format from outFile extension or default to png
+          const outExt = entry.outFile
+            ? entry.outFile.split(".").pop().toLowerCase()
+            : "png";
+          const format = outExt === "jpg" || outExt === "jpeg" ? "jpeg" : "png";
+          const defaultExt = format === "jpeg" ? "jpg" : "png";
+
+          // Single-template: use entry.name as filename (e.g. logo-1024.png)
+          // Multi-template: use template.name as filename (e.g. 01-hero.png)
+          const fileName = singleTemplate && multipleSizes
+            ? `${entry.name}.${defaultExt}`
+            : `${template.name}.${defaultExt}`;
+
+          let outPath;
+          if (entry.outFile) {
+            let resolved = entry.outFile.replace(/\{template\}/g, template.name);
+            if (locale) {
+              resolved = resolved.replace(/\{locale\}/g, locale);
+            }
+            outPath = resolve(projectDir, resolved);
+          } else {
+            outPath = join(sizeDir, fileName);
+          }
+
+          // Asset key and variant key include locale for cache isolation
+          const assetKey = locale
+            ? `${col.id}/${locale}/${template.name}`
+            : `${col.id}/${template.name}`;
+          const variantKey = entry.name;
+          const srcPath = resolve(projectDir, template.src);
+          const checksum = deps.computeChecksum(srcPath);
+          const exportCksum = computeExportChecksum(entry, locale);
+
+          // Skip if unchanged
+          if (
+            !options.force &&
+            checksum &&
+            deps.isUpToDate(lockData, assetKey, variantKey, checksum, outPath, exportCksum)
+          ) {
+            _log(
+              `  Skipping ${template.name}${locale ? ` [${locale}]` : ""} at ${w}x${h} (unchanged)`
+            );
+            skipped++;
+            continue;
+          }
+
+          _log(
+            `  Rendering ${template.name}${locale ? ` [${locale}]` : ""} at ${w}x${h}...`
+          );
+
+          const isSvg = template.src.endsWith(".svg");
+          if (isSvg && w === sourceW && h === sourceH) {
+            copyFileSync(srcPath, outPath.replace(`.${defaultExt}`, ".svg"));
+          }
+
+          // Ensure output directory exists when using outFile
+          if (entry.outFile) {
+            mkdirSync(resolve(projectDir, join(outPath, "..")), { recursive: true });
+          }
+
+          const buffer = await deps.renderScreenshot(
+            projectDir,
+            template.src,
+            w,
+            h,
+            sourceW,
+            sourceH,
+            { format, background: col.background, localization }
+          );
+          writeFileSync(outPath, buffer);
+          results.push({
+            collection: col.id,
+            template: template.name,
+            locale: locale || undefined,
+            path: outPath,
+            width: w,
+            height: h,
+            size: buffer.length,
+          });
+          if (checksum) {
+            deps.recordExport(lockData, assetKey, variantKey, checksum, outPath, exportCksum);
+          }
+          _log(`    → ${outPath}`);
         }
-        _log(`    → ${outPath}`);
       }
     }
 

package/lib/renderer.mjs

@@ -27,7 +27,7 @@ export async function closeBrowser() {
  * @param {number} height
  * @param {number} sourceW
  * @param {number} sourceH
- * @param {{ format?: "png"|"jpeg", quality?: number, background?: string }} [options]
+ * @param {{ format?: "png"|"jpeg", quality?: number, background?: string, localization?: { strings: object, locale: string, direction: string } }} [options]
  */
 export async function renderScreenshot(
   projectDir,
@@ -49,6 +49,51 @@ export async function renderScreenshot(
   await page.goto(`file://${filePath}`, { waitUntil: "networkidle0" });
   await new Promise((r) => setTimeout(r, 500));
 
+  // Inject localized strings and set lang/dir before rendering
+  if (options.localization) {
+    const { strings, locale, direction } = options.localization;
+    await page.evaluate((strings, locale, dir) => {
+      // Set lang on root for font selection; do NOT set dir on root
+      // because it flips the entire CSS layout (flexbox, margins, etc.)
+      // which breaks fixed-pixel marketing layouts.
+      document.documentElement.lang = locale;
+
+      const formatter = new Intl.NumberFormat(locale);
+
+      function processValue(value) {
+        return value.replace(/\{\{n:(\d+(?:\.\d+)?)\}\}/g, (_, num) => {
+          return formatter.format(parseFloat(num));
+        });
+      }
+
+      const walker = document.createTreeWalker(
+        document.documentElement,
+        NodeFilter.SHOW_TEXT
+      );
+      while (walker.nextNode()) {
+        const node = walker.currentNode;
+        let text = node.textContent;
+        let changed = false;
+        text = text.replace(/\{\{([a-zA-Z_][\w.]*)\}\}/g, (match, key) => {
+          if (strings[key] !== undefined) {
+            changed = true;
+            return processValue(strings[key]);
+          }
+          return match;
+        });
+        if (changed) {
+          node.textContent = text;
+          // Apply text direction on the parent element so RTL text
+          // renders correctly without flipping the overall page layout.
+          if (dir === "rtl") {
+            node.parentElement.dir = dir;
+          }
+        }
+      }
+    }, strings, locale, direction);
+    await new Promise((r) => setTimeout(r, 200));
+  }
+
   if (scale !== 1) {
     await page.evaluate((z) => {
       document.documentElement.style.zoom = z;

package/lib/server.mjs

@@ -2,6 +2,7 @@ import { createServer } from "http";
 import { readFileSync, existsSync, statSync, watch } from "fs";
 import { resolve, join, extname } from "path";
 import { fileURLToPath } from "url";
+import { loadLocalizations, resolveStrings, getLocales, getDirection } from "./localization.mjs";
 
 const __dirname = resolve(fileURLToPath(import.meta.url), "..");
 const VIEWER_PATH = join(__dirname, "..", "public", "viewer.html");
@@ -146,7 +147,7 @@ export async function startServer(projectDir, options = {}, renderer) {
     // API: render screenshot (unified for all collection types)
     if (req.method === "POST" && pathname === "/api/render-screenshot") {
       try {
-        const { file, width, height, sourceW, sourceH, background } = JSON.parse(
+        const { file, width, height, sourceW, sourceH, background, localization } = JSON.parse(
           await readBody(req)
         );
         if (!file || !width || !height) {
@@ -157,8 +158,8 @@ export async function startServer(projectDir, options = {}, renderer) {
         }
         const sw = sourceW || width;
         const sh = sourceH || height;
-        log(`Rendering ${file} at ${width}x${height} (source ${sw}x${sh})...`);
-        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh, { background });
+        log(`Rendering ${file} at ${width}x${height} (source ${sw}x${sh})${localization ? ` [${localization.locale}]` : ''}...`);
+        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh, { background, localization });
         res.writeHead(200, {
           "Content-Type": "image/png",
           "Content-Length": buffer.length,
@@ -172,6 +173,32 @@ export async function startServer(projectDir, options = {}, renderer) {
       return;
     }
 
+    // API: get localization data for a collection
+    if (req.method === "GET" && pathname === "/api/localizations") {
+      try {
+        const colId = url.searchParams.get("collection");
+        if (!colId) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          return res.end(JSON.stringify({ ok: false, error: "Missing collection param" }));
+        }
+        const col = manifest.collections.find((c) => c.id === colId);
+        if (!col || !col.localizations) {
+          res.writeHead(404, { "Content-Type": "application/json" });
+          return res.end(JSON.stringify({ ok: false, error: "Collection has no localizations" }));
+        }
+        const data = loadLocalizations(projectDir, col.localizations);
+        const locales = getLocales(data, col.locales);
+        const defaultLocale = manifest.defaultLocalization || data.sourceLanguage || "en";
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true, data, locales, defaultLocale }));
+      } catch (err) {
+        console.error(err);
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: err.message }));
+      }
+      return;
+    }
+
     // API: run xcode output for a collection
     if (req.method === "POST" && pathname === "/api/run-output") {
       try {

package/lib/validate.mjs

@@ -1,6 +1,7 @@
 import { existsSync } from "fs";
 import { resolve } from "path";
 import { flatSizes, flatOutputs } from "./manifest.mjs";
+import { loadLocalizations, getLocales } from "./localization.mjs";
 
 /**
  * Validate a config object and check that referenced files exist.
@@ -82,6 +83,35 @@ export function validateConfig(manifest, projectDir) {
       ok(`Collection "${col.id}" has ${sizes.length} export size(s)`);
     }
 
+    // Validate localizations if configured
+    if (col.localizations) {
+      const l10nPath = resolve(projectDir, col.localizations);
+      if (!existsSync(l10nPath)) {
+        fail(`Collection "${col.id}" localizations file not found: ${col.localizations}`);
+      } else {
+        try {
+          const l10nData = loadLocalizations(projectDir, col.localizations);
+          if (!l10nData.sourceLanguage) {
+            fail(`Collection "${col.id}" localizations missing "sourceLanguage"`);
+          }
+          if (!l10nData.strings || Object.keys(l10nData.strings).length === 0) {
+            fail(`Collection "${col.id}" localizations has no strings defined`);
+          } else {
+            const locales = getLocales(l10nData, col.locales);
+            ok(`Collection "${col.id}" localizations: ${Object.keys(l10nData.strings).length} key(s), ${locales.length} locale(s)`);
+            if (col.locales) {
+              const missing = col.locales.filter((l) => !locales.includes(l));
+              for (const m of missing) {
+                fail(`Collection "${col.id}" requests locale "${m}" but it is not defined in ${col.localizations}`);
+              }
+            }
+          }
+        } catch (err) {
+          fail(`Collection "${col.id}" localizations error: ${err.message}`);
+        }
+      }
+    }
+
     // Validate outputs (export entries with a type field)
     const outputs = flatOutputs(col);
     for (const output of outputs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-assets/open-assets",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Dev server and export tool for app screenshots, icons, and logos. Like Storybook for marketing assets.",
   "type": "module",
   "bin": {

package/public/viewer.html

@@ -80,6 +80,14 @@
 
       .hint { position: fixed; bottom: 12px; left: 50%; transform: translateX(-50%); font-size: 11px; color: #555; z-index: 100; pointer-events: none; }
       .hint kbd { display: inline-block; padding: 1px 5px; border: 1px solid #444; border-radius: 3px; background: #1a1a1a; font-family: inherit; font-size: 10px; color: #888; }
+
+      /* Locale picker */
+      .locale-picker { display: none; align-items: center; gap: 6px; margin-left: 8px; }
+      .locale-picker.visible { display: flex; }
+      .locale-picker label { font-size: 11px; color: #666; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; }
+      .locale-select { padding: 4px 8px; border-radius: 5px; border: 1px solid rgba(255,255,255,0.12); background: rgba(255,255,255,0.06); color: #ccc; font-size: 12px; font-weight: 600; font-family: inherit; cursor: pointer; appearance: none; -webkit-appearance: none; padding-right: 22px; background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='6' fill='none'%3E%3Cpath d='M1 1l4 4 4-4' stroke='%23888' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E"); background-repeat: no-repeat; background-position: right 6px center; }
+      .locale-select:hover { border-color: rgba(255,255,255,0.25); color: #fff; }
+      .locale-select:focus { outline: none; border-color: rgba(255,255,255,0.3); }
     </style>
   </head>
   <body>
@@ -88,6 +96,10 @@
         <img class="toolbar-icon" src="/img/icon/32/icon.png" alt="" />
         <h1 id="app-title">Loading...</h1>
         <div class="segmented" id="tab-bar"></div>
+        <div class="locale-picker" id="locale-picker">
+          <label>Locale</label>
+          <select class="locale-select" id="locale-select"></select>
+        </div>
       </div>
       <div class="toolbar-right">
         <button class="toolbar-btn" id="zoom-out" title="Zoom out">−</button>
@@ -118,6 +130,9 @@
       // ---- State ----
       let manifest = null;
       let activeCollection = null;
+      let localeData = null;       // raw localizations JSON (xcstrings format)
+      let availableLocales = [];   // locale codes for active collection
+      let activeLocale = null;     // currently selected locale (null = no localization)
 
       // ---- DOM refs ----
       const canvas = document.getElementById('canvas');
@@ -127,6 +142,8 @@
       const exportDropdown = document.getElementById('export-dropdown');
       const exportToggle = document.getElementById('export-toggle');
       const toast = document.getElementById('toast');
+      const localePicker = document.getElementById('locale-picker');
+      const localeSelect = document.getElementById('locale-select');
 
       // ---- Zoom / Pan ----
       let scale = 1, panX = 0, panY = 0, isPanning = false, startX = 0, startY = 0, startPanX = 0, startPanY = 0;
@@ -161,12 +178,158 @@
       function showToast(msg) { toast.textContent = msg; toast.classList.add('show'); }
       function hideToast() { toast.classList.remove('show'); }
 
+      // ---- Localization helpers ----
+
+      const RTL_LANGUAGES = new Set(['ar','he','fa','ur','yi','ps','sd','ku','dv','ug']);
+
+      function isRtl(locale) {
+        if (RTL_LANGUAGES.has(locale)) return true;
+        return RTL_LANGUAGES.has(locale.split('-')[0]);
+      }
+
+      function resolveStrings(data, locale) {
+        const strings = {};
+        const sourceLang = data.sourceLanguage || 'en';
+        for (const [key, entry] of Object.entries(data.strings || {})) {
+          const l10ns = entry.localizations || {};
+          const value = l10ns[locale]?.value ?? l10ns[locale.split('-')[0]]?.value ?? l10ns[sourceLang]?.value;
+          if (value !== undefined) strings[key] = value;
+        }
+        return strings;
+      }
+
+      function getLocalization() {
+        if (!activeLocale || !localeData) return undefined;
+        return {
+          strings: resolveStrings(localeData, activeLocale),
+          locale: activeLocale,
+          direction: isRtl(activeLocale) ? 'rtl' : 'ltr',
+        };
+      }
+
+      async function loadLocalizationsForCollection(col) {
+        if (!col.localizations) {
+          localeData = null;
+          availableLocales = [];
+          activeLocale = null;
+          localePicker.classList.remove('visible');
+          return;
+        }
+        try {
+          const res = await fetch(`/api/localizations?collection=${encodeURIComponent(col.id)}`);
+          const json = await res.json();
+          if (!json.ok) throw new Error(json.error);
+          localeData = json.data;
+          availableLocales = json.locales;
+          const defaultLocale = json.defaultLocale;
+
+          // Restore from URL param, or use defaultLocalization, or first available
+          const params = new URLSearchParams(window.location.search);
+          const urlLocale = params.get('locale');
+          if (urlLocale && availableLocales.includes(urlLocale)) {
+            activeLocale = urlLocale;
+          } else if (availableLocales.includes(defaultLocale)) {
+            activeLocale = defaultLocale;
+          } else {
+            activeLocale = availableLocales[0] || null;
+          }
+
+          buildLocalePicker();
+          localePicker.classList.add('visible');
+        } catch (err) {
+          console.error('Failed to load localizations:', err);
+          localeData = null;
+          availableLocales = [];
+          activeLocale = null;
+          localePicker.classList.remove('visible');
+        }
+      }
+
+      function buildLocalePicker() {
+        localeSelect.innerHTML = '';
+        for (const locale of availableLocales) {
+          const opt = document.createElement('option');
+          opt.value = locale;
+          opt.textContent = locale;
+          if (locale === activeLocale) opt.selected = true;
+          localeSelect.appendChild(opt);
+        }
+      }
+
+      localeSelect.addEventListener('change', () => {
+        activeLocale = localeSelect.value;
+        // Update URL without reload
+        const params = new URLSearchParams(window.location.search);
+        params.set('locale', activeLocale);
+        history.replaceState(null, '', '?' + params.toString());
+        applyLocalizationToIframes();
+      });
+
+      function applyLocalizationToIframes() {
+        const l10n = getLocalization();
+        if (!l10n) return;
+        const iframes = inner.querySelectorAll('iframe');
+        for (const iframe of iframes) {
+          applyLocalizationToIframe(iframe, l10n);
+        }
+      }
+
+      function applyLocalizationToIframe(iframe, l10n) {
+        if (!l10n) return;
+        try {
+          const doc = iframe.contentDocument || iframe.contentWindow?.document;
+          if (!doc || !doc.documentElement) return;
+
+          // Reload iframe to get fresh {{key}} placeholders, then inject
+          const src = iframe.dataset.file || iframe.getAttribute('src')?.split('?')[0];
+          if (!src) return;
+
+          iframe.onload = function() {
+            try {
+              const freshDoc = iframe.contentDocument || iframe.contentWindow?.document;
+              if (!freshDoc) return;
+              injectLocalization(freshDoc, l10n);
+            } catch (e) { /* cross-origin or timing */ }
+            iframe.onload = null;
+          };
+          iframe.src = src + '?_l=' + Date.now();
+        } catch (e) { /* ignore */ }
+      }
+
+      function injectLocalization(doc, l10n) {
+        const { strings, locale, direction } = l10n;
+        doc.documentElement.lang = locale;
+
+        const formatter = new Intl.NumberFormat(locale);
+        function processValue(value) {
+          return value.replace(/\{\{n:(\d+(?:\.\d+)?)\}\}/g, (_, num) => formatter.format(parseFloat(num)));
+        }
+
+        const walker = doc.createTreeWalker(doc.documentElement, NodeFilter.SHOW_TEXT);
+        while (walker.nextNode()) {
+          const node = walker.currentNode;
+          let text = node.textContent;
+          let changed = false;
+          text = text.replace(/\{\{([a-zA-Z_][\w.]*)\}\}/g, (match, key) => {
+            if (strings[key] !== undefined) { changed = true; return processValue(strings[key]); }
+            return match;
+          });
+          if (changed) {
+            node.textContent = text;
+            if (direction === 'rtl') node.parentElement.dir = direction;
+          }
+        }
+      }
+
       // ---- Render screenshot via Puppeteer server ----
       async function renderScreenshot(file, width, height, sourceW, sourceH) {
+        const body = { file, width, height, sourceW, sourceH };
+        const l10n = getLocalization();
+        if (l10n) body.localization = l10n;
         const res = await fetch('/api/render-screenshot', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ file, width, height, sourceW, sourceH }),
+          body: JSON.stringify(body),
         });
         if (!res.ok) throw new Error(`Server error: ${res.status}`);
         return await res.blob();
@@ -233,6 +396,15 @@
             iframe.style.width = sw + 'px';
             iframe.style.height = sh + 'px';
 
+            // Apply localization after iframe loads
+            const l10n = getLocalization();
+            if (l10n) {
+              iframe.addEventListener('load', function onLoad() {
+                try { injectLocalization(iframe.contentDocument || iframe.contentWindow.document, l10n); } catch(e) {}
+                iframe.removeEventListener('load', onLoad);
+              });
+            }
+
             border.appendChild(iframe);
             slot.appendChild(border);
           }
@@ -462,6 +634,7 @@
         activeCollection = manifest.collections.find((c) => c.id === colId) || manifest.collections[0];
 
         buildTabBar();
+        await loadLocalizationsForCollection(activeCollection);
         buildCanvas();
         buildExportDropdown();
         requestAnimationFrame(fitAll);
@@ -489,9 +662,16 @@
 
         // Reload iframes whose src matches the changed file
         const iframes = inner.querySelectorAll('iframe');
+        const l10n = getLocalization();
         for (const iframe of iframes) {
           const src = iframe.dataset.file || iframe.getAttribute('src')?.split('?')[0];
           if (src && changedFile.endsWith(src.replace(/^\//, ''))) {
+            if (l10n) {
+              iframe.onload = function() {
+                try { injectLocalization(iframe.contentDocument || iframe.contentWindow.document, l10n); } catch(e) {}
+                iframe.onload = null;
+              };
+            }
             iframe.src = src + bust;
           }
         }
@@ -510,7 +690,15 @@
         if (['css', 'js', 'mjs', 'json', 'woff', 'woff2', 'ttf'].includes(ext)) {
           for (const iframe of iframes) {
             const src = iframe.dataset.file || iframe.getAttribute('src')?.split('?')[0];
-            if (src) iframe.src = src + bust;
+            if (src) {
+              if (l10n) {
+                iframe.onload = function() {
+                  try { injectLocalization(iframe.contentDocument || iframe.contentWindow.document, l10n); } catch(e) {}
+                  iframe.onload = null;
+                };
+              }
+              iframe.src = src + bust;
+            }
           }
         }
       }

package/skills/open-assets/SKILL.md

@@ -194,6 +194,7 @@ Export entries with a `type` field are post-render actions (run with `--force`):
 | `--collection <id>` | Render only the collection with this ID |
 | `--template <name>` | Render only the template with this name |
 | `--size <name>` | Use a named export size from config |
+| `--locale <code>` | Render only this locale (e.g. `en`, `ar`, `ja`) |
 | `-f, --force` | Export at every size and re-render all (ignores cache) |
 | `-o, --output <dir>` | Output directory (default: `./exports`) |
 | `--json` | Output results as JSON |
@@ -335,6 +336,144 @@ The `render` command maintains a `assets.lock` file with SHA256 checksums of sou
 
 Note: only source HTML/SVG files are checksummed. Changes to referenced assets (images in publicDir, compiled CSS) will not trigger re-renders — use `--force` when those change.
 
+## Localization (i18n)
+
+Collections can be localized so that templates render in multiple languages. When localizations are configured, each template is rendered once per locale, producing locale-specific exports with proper text direction (LTR/RTL).
+
+### Localizations file
+
+Create a JSON file (iOS `.xcstrings`-inspired format) that maps string keys to per-locale values:
+
+```json
+{
+  "sourceLanguage": "en",
+  "strings": {
+    "hero_title": {
+      "localizations": {
+        "en": { "value": "Track your tax days" },
+        "ar": { "value": "تتبع أيام الضرائب الخاصة بك" },
+        "ja": { "value": "税金の日を追跡する" },
+        "de": { "value": "Verfolge deine Steuertage" }
+      }
+    },
+    "day_count_label": {
+      "localizations": {
+        "en": { "value": "You have {{n:183}} days remaining" },
+        "ar": { "value": "لديك {{n:183}} يوم متبقي" },
+        "de": { "value": "Sie haben {{n:183}} Tage übrig" }
+      }
+    }
+  }
+}
+```
+
+**Number formatting:** Use `{{n:NUMBER}}` inside localized values for locale-aware number formatting (e.g., `1,234` in English, `1.234` in German). Numbers are formatted using `Intl.NumberFormat` for the target locale.
+
+### Wiring localizations to a collection
+
+Add `localizations` (path to the JSON file) and optionally `locales` (filter to specific locales) to a collection in `assets.json`. You can also set `defaultLocalization` at the root level of `assets.json` to control which locale is selected by default in the dev server's locale picker (falls back to `sourceLanguage` from the localizations file, then `"en"`):
+
+```json
+{
+  "version": 1,
+  "name": "My App",
+  "defaultLocalization": "en",
+  "collections": [
+    {
+      "id": "screenshots",
+      "label": "App Store Screenshots",
+      "sourceSize": { "width": 440, "height": 956 },
+      "localizations": "localizations.json",
+      "locales": ["en", "ar", "ja", "de"],
+      "templates": [
+        { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" }
+      ],
+      "export": [
+        { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } }
+      ]
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `defaultLocalization` | string | Root-level. Default locale for the dev server locale picker. Falls back to `sourceLanguage` then `"en"`. |
+| `localizations` | string | Path to the localizations JSON file (relative to project root) |
+| `locales` | string[] | Optional filter — render only these locales. Omit to render all locales in the file. |
+
+### Dev server locale picker
+
+When a collection has `localizations` configured, the dev server shows a locale picker dropdown in the toolbar. Selecting a locale injects the localized strings into all template iframes in real time. The selected locale is also persisted in the URL (`?locale=ar`) and used for exports — exported PNGs will include the localized text for the active locale.
+
+### Using placeholders in templates
+
+Templates use `{{key}}` mustache-style placeholders that get replaced with localized values before rendering:
+
+```html
+<h1>{{hero_title}}</h1>
+<p>{{day_count_label}}</p>
+```
+
+The source language values serve as the default/fallback content visible during development. At render time, placeholders are substituted with the localized value for each target locale.
+
+### RTL support
+
+Right-to-left locales (Arabic, Hebrew, Persian, Urdu, etc.) are automatically detected. For RTL locales, the renderer sets `dir="rtl"` and `lang` on the `<html>` element before taking the screenshot.
+
+**Design templates with RTL in mind:**
+- Use `logical` CSS properties (`margin-inline-start` instead of `margin-left`, `padding-inline-end` instead of `padding-right`)
+- Use flexbox `gap` instead of directional margins between items
+- Avoid hardcoded `text-align: left` — use `text-align: start` instead
+- For layouts that must flip in RTL, use `[dir="rtl"]` CSS selectors:
+  ```css
+  .arrow { transform: rotate(0deg); }
+  [dir="rtl"] .arrow { transform: rotate(180deg); }
+  ```
+
+### Output structure with locales
+
+When localizations are active, locale codes are inserted into the output path:
+
+```
+exports/
+  screenshots/
+    en/
+      iphone-6.9/
+        01-hero.png
+    ar/
+      iphone-6.9/
+        01-hero.png
+    ja/
+      iphone-6.9/
+        01-hero.png
+```
+
+With `outFile`, use the `{locale}` template variable:
+```json
+{ "outFile": "output/{locale}/{template}.png" }
+```
+
+### CLI
+
+```bash
+# Render all locales for a collection
+open-assets render --collection screenshots --force
+
+# Render only Arabic
+open-assets render --collection screenshots --force --locale ar
+
+# Render a single template in Japanese
+open-assets render --collection screenshots --template 01-hero --locale ja --force
+```
+
+### Locale fallback order
+
+When resolving a string for a locale:
+1. Exact match (e.g., `es-419`)
+2. Base language (e.g., `es`)
+3. Source language (e.g., `en`)
+
 ## File Structure Convention
 
 ```