@menapo/vi18n 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,49 @@
+MIT License
+
+Copyright (c) 2026 menapo
+
+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.
+
+---
+
+dist/ bundles the raw-transfer deserializer of oxc-parser 0.153.0
+(https://github.com/oxc-project/oxc), which is under this license:
+
+MIT License
+
+Copyright (c) 2024-present VoidZero Inc. & Contributors
+Copyright (c) 2023 Boshen
+
+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

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @menapo/vi18n
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+i18n for Vite. Write the source-language string where it is used; vi18n gives
+it an id, keeps `.po` or `.json` catalogs in sync, ships each route's
+translations as a small bundle cut along your build's own chunks, and
+switches languages in place without a reload. One API in React, Preact, Vue,
+Svelte, Solid, Astro and plain JavaScript, in SPAs and in SvelteKit, Astro,
+TanStack Start, React Router, Nuxt, SolidStart and Cloudflare Workers.
+
+**Status: 0.x preview.** Every 1.0 feature is implemented and tested against
+an example app per framework. The docs site, with the guide and the
+benchmarks, is built from this repository; publishing it and the benchmarks
+waits on the repository going public. Until then the repository is private,
+and so is the guide linked below.
+
+```ts
+import { t } from "@menapo/vi18n";
+
+t("Sign out");
+t("Hello {name}", { name: user.name });
+t("{count, plural, =0 {No items} one {# item} other {# items}}", { count });
+t({ id: "hero.cta", message: "Join now", context: "Primary call to action" });
+```
+
+## Why
+
+- **No keys to invent.** A message's id is a hash of its text, computed at
+  build time; the build ships `t("OVaF9kgM8SVi", { name })` and the source
+  text leaves your client JavaScript. Manual ids (`hero.cta`) are there when
+  you want them.
+- **Exact source or nothing.** A translation is used only for the exact text
+  it was made from. Edit the English, and the outdated German stops shipping
+  at once instead of silently lingering.
+- **Per-route bundles from the chunk graph.** No namespaces, no route config:
+  a visitor downloads the strings of the routes they open, in their locale,
+  in parallel with the route's JavaScript. Server-rendered pages hydrate with
+  zero catalog requests, and a translation-only deploy changes no JavaScript
+  file.
+- **In-place switching everywhere.** `setLocale("de")` loads what the page
+  needs, then flips every visible string, `<html lang dir>` and the URL in one
+  step; the plugin generates the framework glue, React Compiler included.
+- **One `handle()` for SSR.** Web-standard per-request isolation, locale
+  negotiation, canonical redirects, SEO alternates and payload injection on
+  Node and Cloudflare Workers (any runtime with `AsyncLocalStorage`).
+- **Catalogs that humans, tools and git can live with.** Standard gettext
+  `.po` (or JSON), deterministic, never wrapped, with the source beside each
+  translation so concurrent edits conflict instead of merging wrongly.
+- **AI translation that validates ICU** (Gemini by default, any
+  OpenAI-compatible API or provider of your own), follows your glossary,
+  marks its output, and never re-requests a string it already has.
+- **Small.** About 2 KB gzip for `t()` and 3 KB for the whole API without
+  `fmt`, plus a client engine of about 3.5 KB loaded once; the test suite
+  enforces a ceiling for each.
+
+## Install
+
+```sh
+vp add @menapo/vi18n
+vp exec vi18n init
+```
+
+`vi18n init` writes `vi18n.config.ts`, adds the plugin to `vite.config.*` and
+creates the catalogs:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import vi18n from "@menapo/vi18n/vite";
+
+export default defineConfig({ plugins: [vi18n()] });
+```
+
+Requires Vite 8.3 or a later 8.x and Node 22.18 or newer.
+
+## Documentation
+
+- [Getting started](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/getting-started.md)
+- [Writing messages](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/messages.md): `t`, ICU, `msg`, rich text, `fmt`, the locale API
+- [Catalogs and the CLI](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/catalogs-and-cli.md): `extract`, `check`, `status`, `compile`, `translate`, `export` / `import`, `restore`, `which`, the git merge driver
+- [Configuration reference](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/configuration.md)
+- [Localized paths, domains and sitemaps](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/localized-urls.md)
+- [Linting](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/lint.md): the `@menapo/vi18n/lint` rules
+- [Testing](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/testing.md): `@menapo/vi18n/test` · [Web Workers](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/workers.md) · [Libraries](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/libraries.md)
+- Recipes: [SPAs](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/recipes/spa.md) (React, Preact, Vue, Svelte, Solid, plain JS) · [SvelteKit](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/recipes/sveltekit.md) · [Astro](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/recipes/astro.md) · [TanStack Start](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/recipes/tanstack-start.md) · [React Router](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/recipes/react-router.md) · [Nuxt](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/recipes/nuxt.md) · [SolidStart](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/recipes/solid-start.md) · [Hono and Workers](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/recipes/hono-workers.md)
+- [Deploying: cache headers per host](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/deploy.md) · [Content Security Policy](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/csp.md)
+- [Migrating from i18next, react-intl, Lingui or vue-i18n](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/migrate-from-libraries.md) · [from `@saas/i18n`](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/migrate-from-saas-i18n.md)
+- Design: [PLAN.md](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/PLAN.md)
+
+The same pages, with the benchmarks, build as a site from
+[`site/`](https://github.com/menapo/vite-plugins/tree/main/site) in the
+repository; `vp run --filter @menapo/site dev` serves it locally.
+
+## Entry points
+
+| Import                 | For                                                                                                                                                                                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@menapo/vi18n`        | App code, browser and server: `t`, `msg`, `rich`, `richHtml`, `richParts`, `fmt`, `getLocale`, `setLocale`, `subscribe`, `setNavigator`, `locales`, `dir`, `localizeHref`, `localizeUrl`, `delocalizeUrl`, `ready`, `preload`, `onMissing`, `T`, `localeName`, `vi18nZod` |
+| `@menapo/vi18n/server` | Servers: `handle`, `withRequest`, `withLocale`, `createTranslator`, `negotiate`, `alternates`, `registerCatalogs` and more                                                                                                                                                |
+| `@menapo/vi18n/parse`  | Text that is not in your code (a CMS, a database): `parse`, `format`, `onParseError`, for ICU and MessageFormat 2                                                                                                                                                         |
+| `@menapo/vi18n/vite`   | The `vi18n()` plugin, and `vi18nTransform()` for Rollup/Rolldown pipelines                                                                                                                                                                                                |
+| `@menapo/vi18n/config` | `defineConfig`, build-time `localizedPaths` and the `openaiCompatible` provider for `vi18n.config.ts`                                                                                                                                                                     |
+| `@menapo/vi18n/lint`   | Lint rules for `vp check`, oxlint or ESLint: untranslated text, dynamic messages, ICU errors with fixes ([guide](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/lint.md))                                                                     |
+| `@menapo/vi18n/test`   | Tests in another locale: `createTestI18n`, `loadCatalog`, `setPseudoLocale`, `scanPseudo` ([guide](https://github.com/menapo/vite-plugins/blob/main/packages/vi18n/docs/guide/testing.md))                                                                                |
+| `vi18n`                | The CLI: `init`, `extract`, `check`, `status`, `compile`, `translate`, `migrate`, `sitemap`, `export`, `import`, `restore`, `which`, `merge-driver`, `lsp`, `mcp`                                                                                                         |
+
+There is no per-framework package: the plugin generates the little glue a
+framework needs from the framework you already use.
+
+## License
+
+MIT

package/dist/apply-Bre-lY9J.js

@@ -0,0 +1,228 @@
+import { o as isDiagnosticError } from "./types-D3QGM8XO.js";
+import { a as isManualId, r as validateTranslation } from "./validate-BxpupdAf.js";
+import { S as entryKey } from "./library-D5CWvTQs.js";
+import { r as resolveDuplicates } from "./duplicates-yuRljQ6h.js";
+import { i as entrySource, r as canonicalOrNull } from "./units-CQ5Q99RC.js";
+//#region src/core/exchange/apply.ts
+/**
+* Applying imported rows and restored entries to a catalog (PLAN §4.3, §4.4,
+* §5.19). Both are pure functions of the catalog they receive, so writers
+* re-run them inside `updateCatalogFile` when the file changed under them.
+* A translation is attached only to the exact source it was made for (D10):
+* a row whose source differs from the entry's is reported, never imported,
+* and a key-only row of a manual id must carry its source's label.
+*/
+/** Every entry index per key: a duplicate gets the same translation as its twin. */
+function keyIndex(catalog, codec) {
+	const index = /* @__PURE__ */ new Map();
+	catalog.entries.forEach((entry, i) => {
+		const key = entryKey(entry, catalog.layout, codec);
+		if (key === null) return;
+		const list = index.get(key);
+		if (list === void 0) index.set(key, [i]);
+		else list.push(i);
+	});
+	return index;
+}
+/** The ICU errors that keep a translation from shipping, as `usableTranslation` finds them. */
+function translationErrors(translation, canonical, codec, locale) {
+	try {
+		const parsed = codec.parse(translation);
+		return validateTranslation(parsed, codec.parse(canonical), {
+			locale,
+			text: translation
+		}).filter((diagnostic) => diagnostic.severity === "error");
+	} catch (error) {
+		if (isDiagnosticError(error)) return [error.diagnostic];
+		throw error;
+	}
+}
+function applyImport(input) {
+	const { catalog, records, context, locale } = input;
+	const { codec } = context;
+	const index = keyIndex(catalog, codec);
+	const resolved = resolveDuplicates(catalog, codec).catalog;
+	const current = /* @__PURE__ */ new Map();
+	for (const entry of resolved.entries) {
+		const key = entryKey(entry, catalog.layout, codec);
+		if (key !== null && !current.has(key)) current.set(key, entry);
+	}
+	const outcome = {
+		catalog,
+		changed: [],
+		unchanged: 0,
+		skipped: [],
+		diagnostics: []
+	};
+	let entries = null;
+	const taken = /* @__PURE__ */ new Map();
+	const skip = (record, reason, id) => {
+		outcome.skipped.push({
+			ref: record.ref,
+			line: record.line,
+			reason,
+			id
+		});
+	};
+	for (const record of records) {
+		if (record.unsupported !== void 0) {
+			skip(record, "unsupported", record.key);
+			continue;
+		}
+		let key = record.key;
+		let recordCanonical = null;
+		if (record.source !== null) {
+			recordCanonical = canonicalOrNull(record.source, codec);
+			if (recordCanonical === null) {
+				skip(record, key === null ? "unknown" : "source-changed", key);
+				continue;
+			}
+			key ??= codec.label(recordCanonical);
+		}
+		const entry = key === null ? void 0 : current.get(key);
+		if (key === null || entry === void 0) {
+			skip(record, "unknown", key);
+			continue;
+		}
+		const source = entrySource(entry, key, context);
+		if (source === null) {
+			skip(record, "no-source", key);
+			continue;
+		}
+		if (recordCanonical !== null) {
+			if (!(context.layout === "id" ? codec.label(recordCanonical) === source.label : recordCanonical === source.canonical)) {
+				skip(record, "source-changed", key);
+				continue;
+			}
+		}
+		if (record.label !== null && record.label !== source.label) {
+			skip(record, "source-changed", key);
+			continue;
+		}
+		if (recordCanonical === null && record.label === null && isManualId(key)) {
+			skip(record, "no-source", key);
+			continue;
+		}
+		if (record.translation === "") {
+			skip(record, "empty", key);
+			continue;
+		}
+		if (record.draft) {
+			skip(record, "draft", key);
+			continue;
+		}
+		const earlier = taken.get(key);
+		if (earlier !== void 0) {
+			if (earlier !== record.translation) skip(record, "duplicate", key);
+			continue;
+		}
+		taken.set(key, record.translation);
+		const errors = translationErrors(record.translation, source.canonical, codec, locale);
+		if (errors.length > 0) {
+			skip(record, "invalid", key);
+			for (const diagnostic of errors) {
+				const located = {
+					...diagnostic,
+					locale,
+					id: key
+				};
+				delete located.column;
+				if (record.line > 0) located.line = record.line;
+				else delete located.line;
+				outcome.diagnostics.push(located);
+			}
+			continue;
+		}
+		const state = record.state ?? (entry.translation === record.translation ? entry.state : "translated");
+		if (entry.translation === record.translation && entry.state === state && !entry.fuzzy) {
+			outcome.unchanged++;
+			continue;
+		}
+		entries ??= catalog.entries.slice();
+		for (const at of index.get(key) ?? []) entries[at] = {
+			...entries[at],
+			translation: record.translation,
+			state,
+			fuzzy: false
+		};
+		outcome.changed.push({
+			id: key,
+			line: record.line
+		});
+	}
+	if (entries !== null) outcome.catalog = {
+		...catalog,
+		entries
+	};
+	return outcome;
+}
+/**
+* Fills the catalog's empty entries from an older revision of it (PLAN
+* §5.19 `vi18n restore`): a generated entry from the old entry with the same
+* canonical source, a manual entry from the old entry with the same manual
+* id and the same canonical source. The old file may record another id
+* scheme, so old entries are matched by text, never by key.
+*/
+function applyRestore(input) {
+	const { catalog, context, old, oldContext, locale } = input;
+	const { codec } = context;
+	const generated = /* @__PURE__ */ new Map();
+	const manual = /* @__PURE__ */ new Map();
+	for (const entry of resolveDuplicates(old, oldContext.codec).catalog.entries) {
+		const key = entryKey(entry, old.layout, oldContext.codec);
+		if (key === null || entry.translation === "" || entry.fuzzy) continue;
+		const source = entrySource(entry, key, oldContext);
+		if (source === null) continue;
+		const map = entry.manualId === null ? generated : manual;
+		const at = entry.manualId === null ? source.canonical : `${entry.manualId}\u0000${source.canonical}`;
+		if (!map.has(at)) map.set(at, entry);
+	}
+	const outcome = {
+		catalog,
+		restored: [],
+		diagnostics: []
+	};
+	let entries = null;
+	catalog.entries.forEach((entry, i) => {
+		if (entry.translation !== "") return;
+		const key = entryKey(entry, catalog.layout, codec);
+		if (key === null) return;
+		const source = entrySource(entry, key, context);
+		if (source === null) return;
+		const found = entry.manualId === null ? generated.get(source.canonical) : manual.get(`${entry.manualId}\u0000${source.canonical}`);
+		if (found === void 0) return;
+		const errors = translationErrors(found.translation, source.canonical, codec, locale);
+		if (errors.length > 0) {
+			for (const diagnostic of errors) {
+				const located = {
+					...diagnostic,
+					locale,
+					id: key
+				};
+				delete located.column;
+				if (entry.line > 0) located.line = entry.line;
+				else delete located.line;
+				outcome.diagnostics.push(located);
+			}
+			return;
+		}
+		entries ??= catalog.entries.slice();
+		entries[i] = {
+			...entry,
+			translation: found.translation,
+			state: found.state,
+			fuzzy: false
+		};
+		outcome.restored.push({
+			id: key,
+			line: entry.line
+		});
+	});
+	if (entries !== null) outcome.catalog = {
+		...catalog,
+		entries
+	};
+	return outcome;
+}
+//#endregion
+export { applyRestore as n, applyImport as t };