@open-assets/open-assets 0.2.0 → 0.3.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/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.3.0",
   "description": "Dev server and export tool for app screenshots, icons, and logos. Like Storybook for marketing assets.",
   "type": "module",
   "bin": {

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,132 @@ 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`:
+
+```json
+{
+  "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 |
+|-------|------|-------------|
+| `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. |
+
+### 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
 
 ```