@omega.js/extension 0.1.0

package/dist/vendor/devkit/test/scope.js

@@ -0,0 +1,162 @@
+/**
+ * Test-scope grammar (C5) — ONE parser for `omega test` targets across every
+ * framework, so scoping means the same thing in a web app, a backend, a
+ * desktop app, and an extension:
+ *
+ *   npx omega test                     → PROJECT tests only (consumer context)
+ *   npx omega test pages/              → project tests under pages/
+ *   npx omega test project:pages/      → same, explicit (`brand:` = alias)
+ *   npx omega test framework:          → the framework's own suite
+ *   npx omega test framework:routes/   → framework suite, scoped
+ *   npx omega test full:               → both sources
+ *   npx omega test full:auth           → both sources, path-scoped
+ *
+ * `omega:` and `mgr:` are universal framework aliases; each framework also
+ * answers to its own id (`backend:`, `desktop:`, `extension:`, `web:`) via
+ * `frameworkAliases`. Bare paths bind to the PROJECT source — reaching the
+ * framework suite is always an explicit choice (Ian 2026-07-11: bare runs
+ * from a brand must never drag the framework corpus in).
+ *
+ * Framework SELF context (running inside the framework package itself —
+ * `selfTest: true`) flips the no-target default to the framework suite, so
+ * each package's own `npm test` keeps meaning "run my suite".
+ */
+
+const UNIVERSAL_FRAMEWORK_ALIASES = ['framework', 'omega', 'mgr'];
+const PROJECT_ALIASES = ['project', 'brand'];
+const FULL_ALIASES = ['full'];
+
+// Per-framework id prefixes, keyed by package name. The SSOT for "which
+// prefixes does each framework answer to": framework runners pass their own
+// entry as `frameworkAliases`, and the manager's brand-root `test` fan-out
+// routes `web:`/`desktop:`/… targets to the target owning that framework.
+// Legacy short ids (ujm/em/bxm) retired with cp262's legacy-name sweep.
+const FRAMEWORK_IDS = {
+  '@omega.js/web': ['web'],
+  '@omega.js/backend': ['backend'],
+  '@omega.js/desktop': ['desktop'],
+  '@omega.js/extension': ['extension'],
+};
+
+/**
+ * Parse `omega test` positional targets into sources + per-source path filters.
+ *
+ * @param {string[]} rawTargets - Positional targets (may be empty)
+ * @param {Object} [options]
+ * @param {string[]} [options.frameworkAliases] - Extra framework prefixes for
+ *   this framework (e.g. ['backend'], ['desktop'], ['extension'], ['web'])
+ * @param {boolean} [options.selfTest] - True when running inside the framework
+ *   package itself (no consumer project)
+ * @returns {{
+ *   sources: string[],                             // subset of ['framework', 'project']
+ *   filters: { framework: string[], project: string[] }, // prefix-stripped path filters per source
+ *   invalid: string[],                             // unrecognized `<word>:` prefixes (likely typos)
+ * }}
+ */
+function parseTestScope(rawTargets, options = {}) {
+  const frameworkAliases = new Set([
+    ...UNIVERSAL_FRAMEWORK_ALIASES,
+    ...(options.frameworkAliases || []),
+  ]);
+
+  const sources = new Set();
+  const filters = { framework: [], project: [] };
+  const invalid = [];
+
+  for (const raw of rawTargets || []) {
+    const target = String(raw).trim();
+    if (!target) continue;
+
+    const match = target.match(/^([a-z-]+):(.*)$/);
+
+    if (!match) {
+      // Bare path — binds to the PROJECT source.
+      sources.add('project');
+      filters.project.push(target);
+      continue;
+    }
+
+    const [, prefix, pathPart] = match;
+
+    if (frameworkAliases.has(prefix)) {
+      sources.add('framework');
+      if (pathPart) filters.framework.push(pathPart);
+    } else if (PROJECT_ALIASES.includes(prefix)) {
+      sources.add('project');
+      if (pathPart) filters.project.push(pathPart);
+    } else if (FULL_ALIASES.includes(prefix)) {
+      sources.add('framework');
+      sources.add('project');
+      if (pathPart) {
+        filters.framework.push(pathPart);
+        filters.project.push(pathPart);
+      }
+    } else {
+      // Unknown prefix — surface it rather than silently matching nothing.
+      invalid.push(target);
+    }
+  }
+
+  // No targets (or only invalid ones): consumer default = project only;
+  // framework self context = the framework's own suite.
+  if (sources.size === 0) {
+    sources.add(options.selfTest ? 'framework' : 'project');
+  }
+
+  return {
+    sources: ['framework', 'project'].filter((s) => sources.has(s)),
+    filters,
+    invalid,
+  };
+}
+
+/**
+ * Did the run ask for test files BY NAME? A path filter (`build/x`,
+ * `project:x`, `desktop:x`, `full:x`) names files; a bare run, or a bare
+ * source prefix, asks for a source. Only the first kind can be a typo, so
+ * only the first kind fails when it selects nothing
+ * ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)).
+ *
+ * @param {{filters: {framework: string[], project: string[]}}} scope - A parseTestScope() result
+ * @returns {boolean} True when at least one path filter was given
+ */
+function isPathTargeted(scope) {
+  return scope.filters.framework.length > 0 || scope.filters.project.length > 0;
+}
+
+/**
+ * The ONE line every framework prints when a named target selects zero test
+ * files: the same sentence in a web app, a backend, a desktop app and an
+ * extension ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)).
+ *
+ * @param {string} target - The target as the caller spelled it
+ * @returns {string} The message (the caller adds its own log tag)
+ */
+function noMatchMessage(target) {
+  return `No test file matches "${target}".`;
+}
+
+// A brand-root run fans ONE target out over every target, where a target that
+// does not carry that path is a legitimate no-op rather than a typo. The
+// manager sets this signal on the runs it forwards and reads the exit code
+// below to tell a miss from a failure
+// ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)). Its presence is
+// the whole signal, the way OMEGA_CASE_RUNNER's is.
+const FANOUT_ENV = 'OMEGA_TEST_FANOUT';
+
+// The exit code a no-match answers with under that signal: distinct, so the
+// fan-out counts misses without confusing them with failures. A standalone run
+// stays 1, the code every human and every CI already reads as "this failed".
+const NO_MATCH_EXIT_CODE = 3;
+
+/**
+ * The exit code a no-match run ends on, given its environment.
+ *
+ * @param {object} [env] - The environment to read (defaults to process.env)
+ * @returns {number} NO_MATCH_EXIT_CODE inside a brand-root fan-out, else 1
+ */
+function noMatchExitCode(env = process.env) {
+  return env[FANOUT_ENV] ? NO_MATCH_EXIT_CODE : 1;
+}
+
+module.exports = { parseTestScope, isPathTargeted, noMatchMessage, noMatchExitCode, NO_MATCH_EXIT_CODE, FANOUT_ENV, UNIVERSAL_FRAMEWORK_ALIASES, PROJECT_ALIASES, FULL_ALIASES, FRAMEWORK_IDS };

package/dist/vendor/devkit/translate/cache.js

@@ -0,0 +1,84 @@
+/**
+ * The committed translation cache — per-string maps keyed by a hash of the
+ * SOURCE string, stored as reviewable JSON in the consumer's `translations/`
+ * directory (committed to git, replacing both the legacy gitignored `.cache/`
+ * and the cache-uj-translation GitHub-branch flow). A source edit changes the
+ * hash → cache miss → only that string re-translates; a human can hand-fix a
+ * translation VALUE and it sticks for as long as the source is unchanged.
+ *
+ * Layout: <rootDir>/<lang>/<namespace>.json  →  { "<hash12>": "translation" }
+ * (namespace = a page path for web, 'messages'/'description' for extension).
+ */
+const path = require('node:path');
+const crypto = require('node:crypto');
+const jetpack = require('fs-jetpack');
+
+/**
+ * Cache key for a source string.
+ * @param {string} source - the source-language string
+ * @returns {string} 12-hex-char sha256 prefix
+ */
+function hashKey(source) {
+  return crypto.createHash('sha256').update(source).digest('hex').slice(0, 12);
+}
+
+/**
+ * Resolve a namespace's cache file path.
+ * @param {string} rootDir - translations root (e.g. <consumer>/translations)
+ * @param {string} lang - language code
+ * @param {string} namespace - cache namespace (slashes allowed)
+ * @returns {string}
+ */
+function cachePath(rootDir, lang, namespace) {
+  return path.join(rootDir, lang, `${namespace}.json`);
+}
+
+/**
+ * Load a namespace's hash → translation map ({} when absent/corrupt).
+ * @param {string} rootDir - translations root
+ * @param {string} lang - language code
+ * @param {string} namespace - cache namespace
+ * @returns {object}
+ */
+function loadCache(rootDir, lang, namespace) {
+  const file = cachePath(rootDir, lang, namespace);
+
+  if (!jetpack.exists(file)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(jetpack.read(file)) || {};
+  } catch (e) {
+    return {};
+  }
+}
+
+/**
+ * Save a namespace's map, pruned to the CURRENT source strings so stale
+ * entries never accumulate. No-op delete when the map is empty.
+ * @param {string} rootDir - translations root
+ * @param {string} lang - language code
+ * @param {string} namespace - cache namespace
+ * @param {object} map - hash → translation
+ * @param {string[]} [currentSources] - prune to these sources' hashes
+ */
+function saveCache(rootDir, lang, namespace, map, currentSources) {
+  let pruned = map;
+
+  if (currentSources) {
+    const keep = new Set(currentSources.map(hashKey));
+    pruned = Object.fromEntries(Object.entries(map).filter(([key]) => keep.has(key)));
+  }
+
+  const file = cachePath(rootDir, lang, namespace);
+
+  if (!Object.keys(pruned).length) {
+    jetpack.remove(file);
+    return;
+  }
+
+  jetpack.write(file, `${JSON.stringify(pruned, null, 2)}\n`);
+}
+
+module.exports = { hashKey, cachePath, loadCache, saveCache };

package/dist/vendor/devkit/translate/engine.js

@@ -0,0 +1,243 @@
+/**
+ * The translation engine — one provider-agnostic protocol for translating a
+ * batch of strings: JSON array in → same-length JSON array out, with a control
+ * sentinel appended to every batch to prove alignment, automatic batching,
+ * validation retries, and a HALVING re-ask for a batch the model keeps
+ * collapsing. Frameworks feed it strings (page text nodes, extension messages)
+ * and get positionally-aligned translations back.
+ */
+
+// Alignment sentinel — appended to every batch, must return unchanged
+const CONTROL = 'OMEGA-TRANSLATION-CONTROL';
+
+const BATCH_SIZE = 25;
+const MAX_RETRIES = 2;
+
+// How many batches are in flight at once (#604). A batch is one model call and
+// the model's latency dominates it, so a serial pass paid that latency once per
+// 25 strings — a language took minutes it never needed to. Raise it only as far
+// as the providers' rate limits allow.
+const CONCURRENCY = 5;
+
+const SYSTEM_PROMPT = `<role>
+Professional translator. Return ONLY a valid JSON array — no commentary, no markdown fences, no wrapping.
+</role>
+
+<task>
+Translate the input JSON array of strings into the target language.
+The output array MUST have the EXACT same length as the input array.
+</task>
+
+<rules>
+- Input: a JSON array of strings. Output: a JSON array of translated strings of the SAME length.
+- DO NOT add, remove, merge, or reorder elements.
+- Consider adjacent strings for context — they come from the same document.
+- Preserve leading and trailing whitespace in each string.
+- Keep HTML tags, attributes, URLs, and email addresses verbatim — never translate them.
+- Preserve placeholder tokens exactly (e.g. $1, $2, %s, {name}, {{ value }}).
+- Keep brand names, product names, and company names in their original language.
+- Never translate the brand name "{brand}".
+- The control string "${CONTROL}" must be returned unchanged at its exact position.
+{extraRules}
+</rules>
+
+<example lang="es">
+Input: ["Welcome to {brand}", "Get started today", "${CONTROL}"]
+Output: ["Bienvenido a {brand}", "Comienza hoy", "${CONTROL}"]
+</example>`;
+
+/**
+ * Parse the provider's response into a JSON array (strips accidental fences).
+ * @param {string} text - raw provider response
+ * @returns {Array} parsed array
+ */
+function parseArrayResponse(text) {
+  const cleaned = (text || '').trim().replace(/^```json?\n?|\n?```$/g, '');
+  const parsed = JSON.parse(cleaned);
+
+  if (!Array.isArray(parsed)) {
+    throw new Error(`translation result is not an array (got ${typeof parsed})`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Re-apply the original string's leading/trailing whitespace to a translation
+ * (models trim despite instructions; surrounding markup relies on it).
+ * @param {string} original - source string
+ * @param {string} translated - translated string
+ * @returns {string}
+ */
+function preserveWhitespace(original, translated) {
+  const leading = original.match(/^\s*/)[0];
+  const trailing = original.match(/\s*$/)[0];
+
+  return `${leading}${String(translated).trim()}${trailing}`;
+}
+
+/**
+ * An alignment failure — the batch came back, but not one-for-one. Marked so
+ * the caller can tell it from a provider that never answered at all.
+ * @param {string} message
+ * @returns {Error}
+ */
+function alignmentError(message) {
+  const error = new Error(message);
+  error.alignment = true;
+  return error;
+}
+
+/**
+ * Translate one batch (with the control sentinel and validation retries).
+ * @param {object} ctx - { send, system, language, languageName }
+ * @param {string[]} batch - strings to translate
+ * @param {number} attempt - current attempt (0-based)
+ * @returns {Promise<{ result: string[], usage: object }>}
+ */
+async function translateBatch(ctx, batch, attempt) {
+  const payload = [...batch, CONTROL];
+  const user = `Target language: ${ctx.language} (${ctx.languageName})\nArray length: ${payload.length}\n\n${JSON.stringify(payload)}`;
+
+  const { text, usage } = await ctx.send({ system: ctx.system, user });
+
+  try {
+    const parsed = parseArrayResponse(text);
+
+    if (parsed.length !== payload.length) {
+      throw alignmentError(`length mismatch: expected ${payload.length}, got ${parsed.length}`);
+    }
+
+    if (parsed[parsed.length - 1] !== CONTROL) {
+      throw alignmentError('control sentinel missing or altered at the last position');
+    }
+
+    return { result: parsed.slice(0, -1), usage };
+  } catch (e) {
+    if (attempt < MAX_RETRIES) {
+      return translateBatch(ctx, batch, attempt + 1);
+    }
+
+    // A batch a model MERGES is deterministic (#523): the playground's
+    // ship-the-docs page came back 25-for-26 on all six attempts, in two
+    // languages — re-asking the same array can only fail the same way. Halving
+    // it separates whatever pair collapsed, and each half is asked in full,
+    // so nothing is guessed at and the page stops shipping untranslated.
+    if (e.alignment && batch.length > 1) {
+      return splitBatch(ctx, batch);
+    }
+
+    throw new Error(`translation failed after ${MAX_RETRIES + 1} attempts: ${e.message}`);
+  }
+}
+
+/**
+ * Re-ask a collapsing batch in halves, bottoming out at one string (a single
+ * string plus the sentinel is unambiguous — a provider that still drops it is
+ * broken, and the caller skips the page-language pair whole).
+ * @param {object} ctx - { send, system, language, languageName }
+ * @param {string[]} batch - the batch that would not come back aligned
+ * @returns {Promise<{ result: string[], usage: object }>}
+ */
+async function splitBatch(ctx, batch) {
+  const middle = Math.ceil(batch.length / 2);
+  const result = [];
+  const usage = { input: 0, output: 0 };
+
+  for (const half of [batch.slice(0, middle), batch.slice(middle)]) {
+    const outcome = await translateBatch(ctx, half, 0);
+    result.push(...outcome.result);
+    usage.input += outcome.usage?.input || 0;
+    usage.output += outcome.usage?.output || 0;
+  }
+
+  return { result, usage };
+}
+
+/**
+ * Run a worker over every item with at most CONCURRENCY of them in flight,
+ * returning results in the ITEMS' order — never completion order.
+ * @param {Array} items - the work items
+ * @param {Function} worker - (item) → Promise
+ * @returns {Promise<Array>} results, positionally aligned with items
+ */
+async function mapLimited(items, worker) {
+  const results = new Array(items.length);
+  let next = 0;
+
+  const drain = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await worker(items[index]);
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, items.length) }, drain));
+
+  return results;
+}
+
+/**
+ * Translate an array of strings, batching + validating along the way.
+ * @param {object} options
+ * @param {string[]} options.strings - source strings
+ * @param {string} options.language - target language code (e.g. 'es')
+ * @param {string} options.languageName - English name of the target language
+ * @param {Function} options.send - provider send ({ system, user }) → { text, usage }
+ * @param {string} [options.brand] - brand name to keep untranslated
+ * @param {string} [options.extraRules] - extra rule lines for the system prompt
+ * @returns {Promise<{ result: string[], usage: { input: number, output: number } }>}
+ *   result is positionally aligned with options.strings, original whitespace preserved
+ */
+async function translateStrings(options) {
+  const { strings, language, languageName, send, brand, extraRules } = options;
+
+  if (!strings.length) {
+    return { result: [], usage: { input: 0, output: 0 } };
+  }
+
+  const system = SYSTEM_PROMPT
+    .split('{brand}').join(brand || 'the brand')
+    .replace('{extraRules}', extraRules ? `${extraRules.trim()}\n` : '');
+
+  const ctx = { send, system, language, languageName };
+  const translated = [];
+  const usage = { input: 0, output: 0 };
+
+  // Dedupe before batching (#529): a page sends its title and description once
+  // per meta tag, so the same string rode a batch three times over — three
+  // times the AI spend, and adjacent twins are exactly what a model merges.
+  // Each unique string is translated ONCE and fanned back below.
+  const unique = [];
+  const position = new Map();
+  for (const string of strings) {
+    if (!position.has(string)) {
+      position.set(string, unique.length);
+      unique.push(string);
+    }
+  }
+
+  const batches = [];
+  for (let i = 0; i < unique.length; i += BATCH_SIZE) {
+    batches.push(unique.slice(i, i + BATCH_SIZE));
+  }
+
+  // Batches fly CONCURRENCY-wide (#604) and are stitched back in BATCH order:
+  // the sentinel, the alignment checks, and the #523 split backstop all stay
+  // per batch, so what a batch does on its own is exactly what it always did.
+  const outcomes = await mapLimited(batches, (batch) => translateBatch(ctx, batch, 0));
+
+  outcomes.forEach((outcome, i) => {
+    translated.push(...outcome.result.map((text, j) => preserveWhitespace(batches[i][j], text)));
+    usage.input += outcome.usage?.input || 0;
+    usage.output += outcome.usage?.output || 0;
+  });
+
+  // Occurrences are keyed on the exact source string, whitespace included, so
+  // every one of them gets back the translation its own text asked for.
+  const result = strings.map((string) => translated[position.get(string)]);
+
+  return { result, usage };
+}
+
+module.exports = { translateStrings, preserveWhitespace, CONTROL, BATCH_SIZE, CONCURRENCY };

package/dist/vendor/devkit/translate/index.js

@@ -0,0 +1,49 @@
+/**
+ * @omega.js/devkit/translate — the shared OMEGA translation system: language
+ * SSOT, provider abstraction (claude via local Claude Code / chatgpt via
+ * OpenAI), the batch translation engine, and the committed per-string cache.
+ * Config contract (shared `translation` section of omega.json5):
+ *   { enabled, default, languages, providers: { claude|chatgpt: {} }, model, exclude }
+ */
+const { chosenProvider } = require('../../config/index.js');
+const { LANGUAGE_NAMES, LANGUAGE_LOCALES, RTL_LANGUAGES, isRTL, languageName, ogLocale, assertKnownLanguages } = require('./languages.js');
+const { PROVIDERS, DEFAULT_MODELS, resolveProvider } = require('./providers.js');
+const { translateStrings, preserveWhitespace, CONTROL, BATCH_SIZE, CONCURRENCY } = require('./engine.js');
+const { hashKey, cachePath, loadCache, saveCache } = require('./cache.js');
+
+/**
+ * Read + validate the `translation` section of a resolved config.
+ * @param {object} config - resolved omega.json5 config
+ * @returns {{ enabled: boolean, default: string, languages: string[], provider: string, model: string|null, exclude: string[] }}
+ *   enabled is false when the section is off or lists no languages
+ */
+function resolveTranslationSettings(config) {
+  const section = config?.translation || {};
+  const languages = section.languages || [];
+
+  assertKnownLanguages(languages);
+
+  return {
+    enabled: section.enabled !== false && languages.length > 0,
+    default: section.default || 'en',
+    languages,
+    // The engine is a KEY under translation.providers (#425); no block at all
+    // means claude, the no-API-key default.
+    provider: chosenProvider(section.providers) || 'claude',
+    model: section.model || null,
+    exclude: section.exclude || [],
+  };
+}
+
+module.exports = {
+  // languages
+  LANGUAGE_NAMES, LANGUAGE_LOCALES, RTL_LANGUAGES, isRTL, languageName, ogLocale, assertKnownLanguages,
+  // providers
+  PROVIDERS, DEFAULT_MODELS, resolveProvider,
+  // engine
+  translateStrings, preserveWhitespace, CONTROL, BATCH_SIZE, CONCURRENCY,
+  // cache
+  hashKey, cachePath, loadCache, saveCache,
+  // config
+  resolveTranslationSettings,
+};

package/dist/vendor/devkit/translate/languages.js

@@ -0,0 +1,134 @@
+/**
+ * Language SSOT for the OMEGA translation system — the code → English-name
+ * map every framework validates against, plus the RTL set. Brand configs pick
+ * target codes in `translation.languages`; frameworks never carry their own
+ * language lists.
+ */
+
+// Supported target languages (ISO 639-1 codes → English names). The names are
+// sent to the AI provider so the model knows exactly which variant is meant.
+const LANGUAGE_NAMES = {
+  ar: 'Arabic',
+  bn: 'Bengali',
+  cs: 'Czech',
+  da: 'Danish',
+  de: 'German',
+  el: 'Greek',
+  es: 'Spanish',
+  fa: 'Persian (Farsi)',
+  fi: 'Finnish',
+  fr: 'French',
+  he: 'Hebrew',
+  hi: 'Hindi',
+  hu: 'Hungarian',
+  id: 'Indonesian',
+  it: 'Italian',
+  ja: 'Japanese',
+  ko: 'Korean',
+  ms: 'Malay',
+  nl: 'Dutch',
+  no: 'Norwegian',
+  pl: 'Polish',
+  pt: 'Portuguese',
+  ro: 'Romanian',
+  ru: 'Russian',
+  sv: 'Swedish',
+  th: 'Thai',
+  tl: 'Tagalog/Filipino',
+  tr: 'Turkish',
+  uk: 'Ukrainian',
+  ur: 'Urdu',
+  vi: 'Vietnamese',
+  zh: 'Chinese (Simplified)',
+};
+
+// Open Graph locales (`language_TERRITORY` — the og:locale convention) for the
+// supported set plus the common source languages. One territory per language:
+// the most widely used one, matching Facebook's locale list (Norwegian is
+// `nb_NO` there, Portuguese `pt_PT`).
+const LANGUAGE_LOCALES = {
+  ar: 'ar_AR',
+  bn: 'bn_IN',
+  cs: 'cs_CZ',
+  da: 'da_DK',
+  de: 'de_DE',
+  el: 'el_GR',
+  en: 'en_US',
+  es: 'es_ES',
+  fa: 'fa_IR',
+  fi: 'fi_FI',
+  fr: 'fr_FR',
+  he: 'he_IL',
+  hi: 'hi_IN',
+  hu: 'hu_HU',
+  id: 'id_ID',
+  it: 'it_IT',
+  ja: 'ja_JP',
+  ko: 'ko_KR',
+  ms: 'ms_MY',
+  nl: 'nl_NL',
+  no: 'nb_NO',
+  pl: 'pl_PL',
+  pt: 'pt_PT',
+  ro: 'ro_RO',
+  ru: 'ru_RU',
+  sv: 'sv_SE',
+  th: 'th_TH',
+  tl: 'tl_PH',
+  tr: 'tr_TR',
+  uk: 'uk_UA',
+  ur: 'ur_PK',
+  vi: 'vi_VN',
+  zh: 'zh_CN',
+};
+
+// Right-to-left languages (drives <html dir="rtl"> on translated pages)
+const RTL_LANGUAGES = ['ar', 'he', 'fa', 'ur', 'ps', 'sd', 'ku', 'yi', 'ckb', 'dv'];
+
+/**
+ * Whether a language renders right-to-left.
+ * @param {string} code - language code
+ * @returns {boolean}
+ */
+function isRTL(code) {
+  return RTL_LANGUAGES.includes(code);
+}
+
+/**
+ * English name for a language code.
+ * @param {string} code - language code
+ * @returns {string} the name, or the code itself if unknown
+ */
+function languageName(code) {
+  return LANGUAGE_NAMES[code] || code;
+}
+
+/**
+ * Open Graph locale for a language code — `es` → `es_ES`. Target codes are
+ * validated by assertKnownLanguages, but the SOURCE language is free-form
+ * config, so an unmapped code falls back to the code itself (a bare code is
+ * what og:locale carried before this map existed).
+ * @param {string} code - language code
+ * @returns {string} the language_TERRITORY locale, or the code if unmapped
+ */
+function ogLocale(code) {
+  return LANGUAGE_LOCALES[code] || code;
+}
+
+/**
+ * Assert every code is a supported target language.
+ * @param {string[]} codes - language codes from config
+ * @throws {Error} naming the unknown codes and the supported set
+ */
+function assertKnownLanguages(codes) {
+  const unknown = (codes || []).filter((code) => !LANGUAGE_NAMES[code]);
+
+  if (unknown.length) {
+    throw new Error(
+      `Unknown translation language(s): ${unknown.join(', ')}. `
+      + `Supported codes: ${Object.keys(LANGUAGE_NAMES).join(', ')}`
+    );
+  }
+}
+
+module.exports = { LANGUAGE_NAMES, LANGUAGE_LOCALES, RTL_LANGUAGES, isRTL, languageName, ogLocale, assertKnownLanguages };