@hyperscript-tools/i18n 2.4.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 LokaScript Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @hyperscript-tools/i18n
+
+Build-time translation for [\_hyperscript](https://hyperscript.org) code
+samples. Ship a single canonical English source; generate `_="..."`
+attributes in any of 24 languages at build time.
+
+Pairs with [`@hyperscript-tools/multilingual`](https://www.npmjs.com/package/@hyperscript-tools/multilingual)
+(runtime translation), so a docs site can choose between _served
+pre-translated_ and _translate on the fly_.
+
+## CLI
+
+```bash
+npx @hyperscript-tools/i18n translate src/page.html --langs ja,es,ko --out dist/
+# Wrote 3 files (1 input × 3 langs) to dist/
+```
+
+Produces `dist/page.ja.html`, `dist/page.es.html`, `dist/page.ko.html` with
+every `_="..."` attribute translated to the target language. The original
+HTML structure is preserved.
+
+### Flags
+
+| Flag            | Description                                                                        |
+| --------------- | ---------------------------------------------------------------------------------- |
+| `--langs`, `-l` | Comma-separated target language codes (`ja,es,ko`).                                |
+| `--out`, `-o`   | Output directory. Defaults to `.`.                                                 |
+| `--from`, `-f`  | Source locale of the input. Defaults to `en`.                                      |
+| `--strict`      | Fail the run on any single attribute that can't be translated. Default is lenient. |
+
+Inputs may be individual files or directories — every `.html` in a directory
+is processed.
+
+## Eleventy plugin
+
+```js
+// eleventy.config.js
+import hyperscriptI18n from '@hyperscript-tools/i18n/eleventy';
+
+export default function (eleventyConfig) {
+  eleventyConfig.addPlugin(hyperscriptI18n);
+}
+```
+
+Adds three filters:
+
+```njk
+{# Translate a single hyperscript snippet #}
+{{ "toggle .active" | translateHs("ja") }}
+{# → ".active を 切り替え" #}
+
+{# Get every translation at once #}
+{% set variants = "toggle .active" | translateHsAll(["ja","es","ko"]) %}
+{% for lang, code in variants %}
+  <code data-hyperscript-lang="{{ lang }}">{{ code }}</code>
+{% endfor %}
+
+{# Rewrite every _="..." attribute in an HTML fragment #}
+{{ patternHtml | translateHsHtml("ja") | safe }}
+```
+
+Filter names can be overridden:
+
+```js
+eleventyConfig.addPlugin(hyperscriptI18n, {
+  filterNames: { snippet: 'toLang', html: 'toLangHtml' },
+});
+```
+
+## Programmatic API
+
+```ts
+import { translate, translateHtml, translateHtmlToManyLangs } from '@hyperscript-tools/i18n';
+
+// Snippet → snippet
+translate('toggle .active', 'en', 'ja');
+// → '.active を 切り替え'
+
+// HTML → HTML (rewrites every _="..." attribute)
+const ja = translateHtml(html, 'ja');
+
+// HTML → Map of HTML
+const variants = translateHtmlToManyLangs(html, ['ja', 'es', 'ko']);
+```
+
+## Supported languages
+
+All 24 languages supported by `@lokascript/i18n`:
+`ar, bn, de, en, es, fr, he, hi, id, it, ja, ko, ms, pl, pt, qu, ru, sw, th, tl, tr, uk, vi, zh`.
+
+Word order is handled automatically: SVO (Spanish, Chinese), SOV (Japanese,
+Korean, Turkish), VSO (Arabic). RTL languages preserve direction.
+
+## When to use this vs. `@hyperscript-tools/multilingual`
+
+| Need                                                             | Reach for                                     |
+| ---------------------------------------------------------------- | --------------------------------------------- |
+| Visitors type hyperscript in their native language at runtime    | `@hyperscript-tools/multilingual`             |
+| Author once in English; ship pre-translated docs in 24 languages | `@hyperscript-tools/i18n` (this)              |
+| Both                                                             | Use both. They share no runtime dependencies. |
+
+## License
+
+MIT.

package/dist/chunk-XIEA5H7Z.js

@@ -0,0 +1,37 @@
+// src/html.ts
+import { translate } from "@lokascript/i18n";
+var ATTR_PATTERNS = [
+  /(_\s*=\s*")([^"]+)(")/g,
+  /(_\s*=\s*')([^']+)(')/g,
+  /(_\s*=\s*`)([^`]+)(`)/g
+];
+function translateHtml(html, to, options = {}) {
+  const from = options.from ?? "en";
+  const lenient = options.lenient ?? true;
+  if (from === to) return html;
+  let out = html;
+  for (const pattern of ATTR_PATTERNS) {
+    out = out.replace(pattern, (_match, before, body, after) => {
+      try {
+        const translated = translate(body, from, to);
+        return `${before}${translated}${after}`;
+      } catch (err) {
+        if (lenient) return `${before}${body}${after}`;
+        throw err;
+      }
+    });
+  }
+  return out;
+}
+function translateHtmlToManyLangs(html, langs, options = {}) {
+  const out = /* @__PURE__ */ new Map();
+  for (const lang of langs) {
+    out.set(lang, translateHtml(html, lang, options));
+  }
+  return out;
+}
+
+export {
+  translateHtml,
+  translateHtmlToManyLangs
+};

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * CLI: hyperscript-i18n
+ *
+ * Usage:
+ *   hyperscript-i18n translate <input.html> --langs ja,es,ko --out dist/
+ *   hyperscript-i18n translate "src/**\/*.html" --langs ja,es,ko --out dist/ --from en
+ *
+ * For each input file and each requested target language, emits a sibling
+ * file in --out named `<basename>.<lang>.html` containing the translated
+ * `_=` attributes. The original English remains the canonical source.
+ */
+declare function run(argv: string[]): Promise<number>;
+
+export { run };

package/dist/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import {
+  translateHtml
+} from "./chunk-XIEA5H7Z.js";
+
+// src/cli.ts
+import { mkdirSync, readFileSync, writeFileSync, existsSync, statSync, readdirSync } from "fs";
+import { dirname, join, basename, extname, resolve } from "path";
+function parseArgs(argv) {
+  const args = {
+    command: "help",
+    inputs: [],
+    langs: [],
+    from: "en",
+    out: ".",
+    strict: false
+  };
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") return args;
+  args.command = argv[0] === "translate" ? "translate" : "help";
+  if (args.command === "help") return args;
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--langs" || a === "-l") {
+      args.langs = (argv[++i] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (a === "--out" || a === "-o") {
+      args.out = argv[++i] ?? ".";
+    } else if (a === "--from" || a === "-f") {
+      args.from = argv[++i] ?? "en";
+    } else if (a === "--strict") {
+      args.strict = true;
+    } else if (a.startsWith("-")) {
+      throw new Error(`Unknown flag: ${a}`);
+    } else {
+      args.inputs.push(a);
+    }
+  }
+  return args;
+}
+function expandInputs(patterns) {
+  const out = [];
+  for (const pattern of patterns) {
+    const abs = resolve(pattern);
+    if (!existsSync(abs)) {
+      console.warn(`Skipping missing input: ${pattern}`);
+      continue;
+    }
+    const stat = statSync(abs);
+    if (stat.isDirectory()) {
+      for (const name of readdirSync(abs)) {
+        if (name.endsWith(".html")) out.push(join(abs, name));
+      }
+    } else {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+function printHelp() {
+  console.log(`hyperscript-i18n \u2014 translate _="..." attributes in HTML
+
+Usage:
+  hyperscript-i18n translate <input> [<input> ...] --langs <codes> --out <dir> [--from <code>] [--strict]
+
+Options:
+  --langs, -l   Comma-separated target language codes (e.g. ja,es,ko).
+  --out, -o     Output directory. Defaults to the current directory.
+  --from, -f    Source locale of the input. Defaults to 'en'.
+  --strict      Fail the run if any single attribute fails to translate.
+                Default is lenient: untranslatable snippets are left in place.
+
+Output:
+  For each input file foo.html and each lang, writes <out>/foo.<lang>.html.
+
+Example:
+  hyperscript-i18n translate src/patterns.html --langs ja,es,ko --out dist/
+`);
+}
+async function run(argv) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    console.error(err.message);
+    return 2;
+  }
+  if (args.command === "help") {
+    printHelp();
+    return 0;
+  }
+  if (args.langs.length === 0) {
+    console.error("No --langs provided.");
+    return 2;
+  }
+  if (args.inputs.length === 0) {
+    console.error("No input files provided.");
+    return 2;
+  }
+  const files = expandInputs(args.inputs);
+  if (files.length === 0) {
+    console.error("No HTML inputs matched.");
+    return 1;
+  }
+  mkdirSync(args.out, { recursive: true });
+  let written = 0;
+  for (const file of files) {
+    const html = readFileSync(file, "utf8");
+    const stem = basename(file, extname(file));
+    for (const lang of args.langs) {
+      const translated = translateHtml(html, lang, {
+        from: args.from,
+        lenient: !args.strict
+      });
+      const outPath = join(args.out, `${stem}.${lang}.html`);
+      mkdirSync(dirname(outPath), { recursive: true });
+      writeFileSync(outPath, translated, "utf8");
+      written++;
+    }
+  }
+  console.log(
+    `Wrote ${written} files (${files.length} input \xD7 ${args.langs.length} langs) to ${args.out}`
+  );
+  return 0;
+}
+var isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  run(process.argv.slice(2)).then((code) => process.exit(code));
+}
+export {
+  run
+};

package/dist/eleventy.d.ts

@@ -0,0 +1,44 @@
+import { LangCode } from './index.js';
+export { TranslateHtmlOptions, translateHtml, translateHtmlToManyLangs } from './index.js';
+import '@lokascript/i18n';
+
+/**
+ * Eleventy plugin entry: `@hyperscript-tools/i18n/eleventy`
+ *
+ * Adds:
+ *   - `translateHs` filter: translate a hyperscript snippet to a target lang.
+ *       {{ snippet | translateHs("ja") }}
+ *       {{ snippet | translateHs("ja", "en") }}     // explicit source
+ *
+ *   - `translateHsAll` filter: produce { lang: translated } for an array of
+ *     target langs. Useful for emitting per-language code blocks side by side.
+ *       {% set variants = snippet | translateHsAll(["ja","es","ko"]) %}
+ *
+ *   - `translateHsHtml` filter: rewrite every `_="..."` attribute in an HTML
+ *     fragment. Useful for `{{ patternHtml | translateHsHtml("ja") | safe }}`.
+ *
+ * Usage:
+ *   import hyperscriptI18n from '@hyperscript-tools/i18n/eleventy';
+ *   export default function (eleventyConfig) {
+ *     eleventyConfig.addPlugin(hyperscriptI18n);
+ *   }
+ */
+
+interface EleventyPluginOptions {
+    /** Default source locale for filters. Defaults to 'en'. */
+    defaultFrom?: LangCode;
+    /** Default lenient flag for HTML translation. Defaults to true. */
+    lenient?: boolean;
+    /** Override filter names (in case of collisions in your config). */
+    filterNames?: {
+        snippet?: string;
+        snippetMany?: string;
+        html?: string;
+    };
+}
+interface EleventyConfig {
+    addFilter(name: string, fn: (...args: unknown[]) => unknown): void;
+}
+declare function hyperscriptI18nPlugin(eleventyConfig: EleventyConfig, options?: EleventyPluginOptions): void;
+
+export { type EleventyPluginOptions, LangCode, hyperscriptI18nPlugin as default };

package/dist/eleventy.js

@@ -0,0 +1,57 @@
+import {
+  translateHtml,
+  translateHtmlToManyLangs
+} from "./chunk-XIEA5H7Z.js";
+
+// src/eleventy.ts
+import { translate } from "@lokascript/i18n";
+function hyperscriptI18nPlugin(eleventyConfig, options = {}) {
+  const defaultFrom = options.defaultFrom ?? "en";
+  const lenient = options.lenient ?? true;
+  const names = {
+    snippet: options.filterNames?.snippet ?? "translateHs",
+    snippetMany: options.filterNames?.snippetMany ?? "translateHsAll",
+    html: options.filterNames?.html ?? "translateHsHtml"
+  };
+  eleventyConfig.addFilter(names.snippet, (input, to, from) => {
+    if (typeof input !== "string" || typeof to !== "string") return input;
+    const source = typeof from === "string" ? from : defaultFrom;
+    if (source === to) return input;
+    try {
+      return translate(input, source, to);
+    } catch {
+      return lenient ? input : "";
+    }
+  });
+  eleventyConfig.addFilter(names.snippetMany, (input, langs, from) => {
+    if (typeof input !== "string" || !Array.isArray(langs)) return {};
+    const source = typeof from === "string" ? from : defaultFrom;
+    const out = {};
+    for (const lang of langs) {
+      if (typeof lang !== "string") continue;
+      if (lang === source) {
+        out[lang] = input;
+        continue;
+      }
+      try {
+        out[lang] = translate(input, source, lang);
+      } catch {
+        out[lang] = lenient ? input : "";
+      }
+    }
+    return out;
+  });
+  eleventyConfig.addFilter(names.html, (html, to, from) => {
+    if (typeof html !== "string" || typeof to !== "string") return html;
+    const opts = {
+      from: typeof from === "string" ? from : defaultFrom,
+      lenient
+    };
+    return translateHtml(html, to, opts);
+  });
+}
+export {
+  hyperscriptI18nPlugin as default,
+  translateHtml,
+  translateHtmlToManyLangs
+};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export { GrammarTransformer, toEnglish, toLocale, translate } from '@lokascript/i18n';
+
+/**
+ * HTML attribute scanner + translator.
+ *
+ * Walks an HTML string, finds `_="..."` (and single-quoted / backtick variants)
+ * attributes, translates each from a source locale to a target locale, and
+ * returns the rewritten HTML. The grammar transformer doesn't know about HTML;
+ * this module is the glue.
+ */
+type LangCode = string;
+interface TranslateHtmlOptions {
+    /** Source locale of the input HTML's `_=` attributes. Defaults to 'en'. */
+    from?: LangCode;
+    /**
+     * If true, swallow per-attribute translation errors and leave the original
+     * text in place. Defaults to true so a single bad sample doesn't fail the
+     * whole page build.
+     */
+    lenient?: boolean;
+}
+declare function translateHtml(html: string, to: LangCode, options?: TranslateHtmlOptions): string;
+declare function translateHtmlToManyLangs(html: string, langs: ReadonlyArray<LangCode>, options?: TranslateHtmlOptions): Map<LangCode, string>;
+
+export { type LangCode, type TranslateHtmlOptions, translateHtml, translateHtmlToManyLangs };

package/dist/index.js

@@ -0,0 +1,15 @@
+import {
+  translateHtml,
+  translateHtmlToManyLangs
+} from "./chunk-XIEA5H7Z.js";
+
+// src/index.ts
+import { translate, toLocale, toEnglish, GrammarTransformer } from "@lokascript/i18n";
+export {
+  GrammarTransformer,
+  toEnglish,
+  toLocale,
+  translate,
+  translateHtml,
+  translateHtmlToManyLangs
+};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@hyperscript-tools/i18n",
+  "version": "2.4.0",
+  "description": "Build-time translation for hyperscript code samples — generate per-language HTML from a canonical English source",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "hyperscript-i18n": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./eleventy": {
+      "types": "./dist/eleventy.d.ts",
+      "import": "./dist/eleventy.js"
+    },
+    "./cli": {
+      "default": "./dist/cli.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts src/eleventy.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts src/cli.ts src/eleventy.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "pretest": "../../scripts/ensure-fresh.sh ../i18n . && npm run build --silent",
+    "test": "node --test test/*.test.mjs",
+    "test:check": "node --test --test-reporter=spec test/*.test.mjs 2>&1 | tail -10"
+  },
+  "keywords": [
+    "hyperscript",
+    "_hyperscript",
+    "i18n",
+    "internationalization",
+    "translation",
+    "build-time",
+    "eleventy",
+    "11ty",
+    "cli",
+    "static-site"
+  ],
+  "author": "HyperFixi Contributors",
+  "license": "MIT",
+  "dependencies": {
+    "@lokascript/i18n": "^2.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codetalcott/hyperfixi.git",
+    "directory": "packages/hyperscript-tools-i18n"
+  },
+  "bugs": {
+    "url": "https://github.com/codetalcott/hyperfixi/issues"
+  },
+  "homepage": "https://github.com/codetalcott/hyperfixi/tree/main/packages/hyperscript-tools-i18n#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}