@wads.dev/i18n-html 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wads.dev
+
+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,50 @@
+# @wads.dev/i18n-html
+
+Typed DOM bindings and static HTML usage discovery for catalogs built with [`@wads.dev/i18n-ts`](https://github.com/wads-dev/i18n-ts).
+
+> Status: `0.0.1-alpha.0`. The API may change before `1.0.0`.
+
+## Install
+
+```sh
+npm install @wads.dev/i18n-ts@alpha @wads.dev/i18n-html@alpha
+```
+
+## Translate a document
+
+Use `data-i18n` for element text and `data-i18n-{attribute}` for attributes.
+
+```html
+<h1 data-i18n="page.title">Loading…</h1>
+<input data-i18n-placeholder="search.placeholder" placeholder="Loading…">
+```
+
+```ts
+import { translateHtml } from '@wads.dev/i18n-html'
+
+translateHtml(document, Lang)
+```
+
+`translateHtml` is explicit. It does not watch the DOM or keep its own language state; call it after loading or changing the language.
+
+## Discover static HTML usage
+
+Tooling can recognize the same contract through the Node-only entry point:
+
+```ts
+import { collectHtmlI18nReferences } from '@wads.dev/i18n-html/usage'
+
+const references = collectHtmlI18nReferences({
+  directory: process.cwd(),
+  ignoredDirectories: ['src/i18n'],
+})
+```
+
+Each reference contains the translation key plus the relative file, line and column.
+
+## Ecosystem
+
+- [`@wads.dev/i18n-ts`](https://github.com/wads-dev/i18n-ts): typed contracts, language loading, bundles and configuration.
+- [`@wads.dev/i18n-react`](https://github.com/wads-dev/i18n-react): React adapter.
+- [`@wads.dev/i18n-html`](https://github.com/wads-dev/i18n-html): DOM/HTML adapter.
+- [`@wads.dev/i18n-editor`](https://github.com/wads-dev/i18n-editor): local bundle editor and project exporter.

package/dist/runtime/index.d.ts

@@ -0,0 +1,4 @@
+import type { DeepReadonly, Translation } from '@wads.dev/i18n-ts';
+export type HtmlTranslationTree = DeepReadonly<Translation>;
+export declare function readHtmlTranslation(translations: HtmlTranslationTree, key: string): string;
+export declare function translateHtml(document: Document, translations: HtmlTranslationTree): void;

package/dist/runtime/index.js

@@ -0,0 +1,27 @@
+function readTranslationValue(translations, key) {
+    return key.split('.').reduce((current, segment) => {
+        return current && typeof current === 'object' ? current[segment] : undefined;
+    }, translations);
+}
+export function readHtmlTranslation(translations, key) {
+    const value = readTranslationValue(translations, key);
+    if (typeof value !== 'string')
+        throw new Error(`HTML translation must resolve to a string: ${key}`);
+    return value;
+}
+export function translateHtml(document, translations) {
+    document.querySelectorAll('[data-i18n]').forEach((element) => {
+        const key = element.dataset.i18n;
+        if (key)
+            element.textContent = readHtmlTranslation(translations, key);
+    });
+    document.querySelectorAll('*').forEach((element) => {
+        Array.from(element.attributes).forEach((attribute) => {
+            if (!attribute.name.startsWith('data-i18n-'))
+                return;
+            const targetAttribute = attribute.name.slice('data-i18n-'.length);
+            if (targetAttribute)
+                element.setAttribute(targetAttribute, readHtmlTranslation(translations, attribute.value));
+        });
+    });
+}

package/dist/usage/index.d.ts

@@ -0,0 +1,11 @@
+export type HtmlI18nReference = {
+    key: string;
+    file: string;
+    line: number;
+    column: number;
+};
+export type CollectHtmlI18nReferencesOptions = {
+    directory: string;
+    ignoredDirectories?: string[];
+};
+export declare function collectHtmlI18nReferences({ directory, ignoredDirectories, }: CollectHtmlI18nReferencesOptions): HtmlI18nReference[];

package/dist/usage/index.js

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+function isInside(filePath, directory) {
+    const relative = path.relative(directory, filePath);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function collectHtmlFiles(directory, ignoredDirectories, result = []) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        const filePath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === '.git' || entry.name === 'dist' || entry.name === 'node_modules')
+                continue;
+            if (ignoredDirectories.some((ignoredDirectory) => isInside(filePath, ignoredDirectory)))
+                continue;
+            collectHtmlFiles(filePath, ignoredDirectories, result);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.html')) {
+            result.push(filePath);
+        }
+    }
+    return result;
+}
+function lineAndColumn(content, offset) {
+    const before = content.slice(0, offset);
+    const line = before.split('\n').length;
+    return { line, column: offset - before.lastIndexOf('\n') };
+}
+export function collectHtmlI18nReferences({ directory, ignoredDirectories = [], }) {
+    const resolvedDirectory = path.resolve(directory);
+    const resolvedIgnoredDirectories = ignoredDirectories.map((ignoredDirectory) => path.resolve(ignoredDirectory));
+    const attributePattern = /\bdata-i18n(?:-[\w-]+)?\s*=\s*(["'])([^"']+)\1/g;
+    return collectHtmlFiles(resolvedDirectory, resolvedIgnoredDirectories).flatMap((filePath) => {
+        const content = fs.readFileSync(filePath, 'utf8');
+        return [...content.matchAll(attributePattern)].map((match) => {
+            const key = match[2];
+            const keyOffset = (match.index ?? 0) + match[0].lastIndexOf(key);
+            const position = lineAndColumn(content, keyOffset);
+            return {
+                key,
+                file: path.relative(resolvedDirectory, filePath).replaceAll(path.sep, '/'),
+                line: position.line,
+                column: position.column,
+            };
+        });
+    });
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@wads.dev/i18n-html",
+  "version": "0.0.1-alpha.0",
+  "description": "Typed HTML bindings and static usage discovery for @wads.dev/i18n-ts catalogs.",
+  "license": "MIT",
+  "author": {
+    "name": "Wads.dev",
+    "url": "https://github.com/wads-dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wads-dev/i18n-html.git"
+  },
+  "homepage": "https://github.com/wads-dev/i18n-html#readme",
+  "bugs": {
+    "url": "https://github.com/wads-dev/i18n-html/issues"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "html",
+    "typescript",
+    "translations"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "node ./scripts/clean-dist.mjs",
+    "check": "tsc --project tsconfig.check.json --noEmit",
+    "build": "npm run clean && tsc --project tsconfig.build.json",
+    "prepack": "npm run check && npm run build"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./usage": {
+      "types": "./dist/usage/index.d.ts",
+      "import": "./dist/usage/index.js"
+    }
+  },
+  "dependencies": {
+    "@wads.dev/i18n-ts": "^0.0.1-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}