@voltro/i18n 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to the `@voltro/*` packages are recorded here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## Stability contract — read this before you pin a version
+
+Voltro is **`0.x` — pre-1.0, and deliberately so.** Under SemVer, `0.y.z` means
+"anything MAY change." We hold to exactly that, stated out loud:
+
+- **Pin exact versions.** Depend on `@voltro/runtime@0.4.2`, never `^0.4.2` or
+  `~0.4.2`. There is no compatible-range promise below 1.0.
+- **Every MINOR may break.** Breaking changes land on a minor bump (`0.4.x →
+  0.5.0`); patches (`0.4.1 → 0.4.2`) are additive or fixes only. This is the
+  standard `0.x` reading of SemVer — the minor slot carries breaking under `0.x`.
+- **Read this changelog before upgrading.** The `⚠ BREAKING` section of each
+  release lists every incompatible change with its migration. It is the only
+  migration path we provide — there is no deprecation cycle, no compat shim.
+- **All packages release together (lockstep).** One coordinated version across
+  the whole framework; the git tag is the source of truth.
+
+This is not a placeholder disclaimer — it is the contract. The framework is
+refactored aggressively while it has no external stability obligations, and that
+velocity is the point. A stable-core tier and per-package `1.0` graduation are
+planned, but not yet; until then, treat the whole surface as movable and pin
+exact.
+
+The **public API** of each package is its `publishConfig.exports` entry points,
+minus anything marked `@internal` (those are cross-package internals and are
+stripped from the published `.d.ts`). Importing a deep path that isn't an
+exported entry point is unsupported.
+
+---
+
+## [Unreleased]
+
+_Changes staged for the next release accumulate here (rolled up from
+`.changes/*.md` at tag time — see `.changes/README.md`)._
+
+---
+
+## [0.1.0]
+
+Initial pre-release baseline. This is the starting point the changelog tracks
+from; it is not an exhaustive history of prior development. The framework ships
+as `@voltro/*` packages spanning the runtime, database/query layer, web client
+and router, durable workflows, the CLI, and the plugin ecosystem
+(auth, storage, mail, billing, observability, and more). Not published to a
+public registry yet.
+
+Subsequent releases record their deltas from here under dated headings, with
+`⚠ BREAKING` first.

package/LICENSE

@@ -0,0 +1,57 @@
+Voltro — Proprietary Software License
+
+Copyright (c) 2026 Voltro UG. All rights reserved.
+
+This software and all associated source code, documentation, and other
+materials (the "Software") are the proprietary property of Voltro UG
+("Voltro"). This is NOT open-source software.
+
+Your access to and use of the Software is governed exclusively by the Voltro
+Terms of Service at:
+
+    https://voltro.cloud/legal/terms
+
+By downloading, installing, or using the Software you agree to those Terms.
+Subject to and conditioned on your continued compliance with them, Voltro
+grants you a limited, non-exclusive, non-transferable, non-sublicensable,
+revocable license to use the Software. All rights not expressly granted in the
+Terms are reserved by Voltro. If you do not agree to the Terms, you have no
+license and may not use the Software.
+
+The Terms of Service — including the scope of permitted use, plan
+entitlements, fees, and pricing — may change from time to time. The version in
+force is the one published at the URL above. Commercial terms and pricing are
+NOT part of this notice and are not fixed by, or granted in perpetuity by, the
+version of the Software in which this file appears.
+
+Permitted use — your own software. Voltro is a development framework. You may
+use the Software to build, run, and commercially distribute your own
+applications and services, and to charge your own customers for them, without
+owing Voltro any share of that revenue or any further permission beyond the
+Terms. Applications you build with the Software are yours.
+
+Prohibited use — reselling Voltro. You may NOT redistribute, resell,
+sublicense, publish, or otherwise provide the Software itself — in whole or in
+part, in source or compiled form — to third parties as a library, framework,
+SDK, template, starter, or development tool for them to build upon, whether
+standalone or repackaged. Shipping the Software as a non-separable, bundled
+dependency inside an application you deliver (for example, compiled into your
+deployed app) is permitted; extracting or re-exposing it as a reusable
+component for others is not.
+
+Except as expressly permitted above or by the Terms, you may not copy, modify,
+merge, publish, sublicense, sell, distribute, or create derivative works of the
+Software, in whole or in part.
+
+Third-party open-source components distributed alongside the Software are the
+property of their respective owners and are licensed under their own terms; see
+THIRD-PARTY-NOTICES.md where provided. Nothing in this notice limits your
+rights, or extends Voltro's, in those components.
+
+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
+VOLTRO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+For licensing inquiries, contact Voltro UG.

package/README.md

@@ -0,0 +1,26 @@
+<div align="center">
+
+# @voltro/i18n
+
+**Voltro's i18n layer — thin opinionated wrap over react-intl. Provides the framework's locale-resolution conventions (voltro:lang cookie + Accept-Language fallback), a typed message-catalog helper, and a slim provider component. Power users can import directly from react-intl for advanced APIs.**
+
+[📖 Documentation](https://docs.voltro.dev/docs/i18n/overview) · [Changelog](./CHANGELOG.md) · [voltro.dev](https://voltro.dev) · [Voltro Cloud](https://voltro.cloud)
+
+</div>
+
+---
+
+```sh
+npm install @voltro/i18n
+```
+
+> ### [→ Read the documentation for @voltro/i18n](https://docs.voltro.dev/docs/i18n/overview)
+
+Installation, guides, the full API reference, and examples all live in the
+**[Voltro documentation](https://docs.voltro.dev/docs/intro/getting-started)** — the single source of truth. This README is
+deliberately short so there is nothing here to drift out of date.
+
+## License
+
+Proprietary. © 2026 Voltro UG. Your use is governed by the
+[Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+We take the security of Voltro and the applications built on it seriously. This
+document explains how to report a vulnerability and what to expect in return.
+
+## Reporting a vulnerability
+
+**Please do not open public issues or discuss suspected vulnerabilities in
+public channels.** Report them privately by email:
+
+**security contact: [support@voltro.dev](mailto:support@voltro.dev)**
+(subject line: `SECURITY`).
+
+Include, where you can:
+
+- the affected package(s) and version(s) (e.g. `@voltro/runtime@x.y.z`);
+- a description of the issue and its impact;
+- a minimal reproduction or proof of concept;
+- any suggested remediation.
+
+If you'd like to encrypt your report, ask in a first plain email and we'll
+arrange a key.
+
+## What to expect
+
+- **Acknowledgement** of your report within **3 business days**.
+- An initial assessment (severity, affected surface) and a remediation plan as
+  soon as we've reproduced the issue.
+- **Coordinated disclosure:** we'll agree a disclosure timeline with you and
+  credit you in the release notes if you wish. Please give us reasonable time to
+  ship a fix before any public disclosure.
+
+We do not currently run a paid bug-bounty program, but we genuinely appreciate
+responsible disclosure and will credit reporters.
+
+## Software Bill of Materials (SBOM)
+
+A CycloneDX SBOM of the third-party runtime dependency graph is generated for the
+published packages (`pnpm gen:sbom` → `sbom.cdx.json`). If your procurement or
+security team needs it, request it at
+[support@voltro.dev](mailto:support@voltro.dev).
+
+## Supported versions
+
+Voltro is pre-1.0 and ships in lockstep: **only the latest published minor of
+each `@voltro/*` package receives security fixes.** Please upgrade to the latest
+release before reporting, and pin exact versions in production.
+
+## Scope
+
+In scope: the published `@voltro/*` packages and the framework's own code.
+
+Out of scope: vulnerabilities in third-party dependencies that are already
+tracked upstream (we monitor these via a production-dependency audit gate in
+CI), and issues that require a non-default, explicitly-unsafe configuration. If
+you're unsure, report it anyway — we'd rather hear about it.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,11 @@
+# Third-Party Notices — @voltro/i18n
+
+This package depends on the open-source software listed below. Each is the
+property of its respective copyright holders and is used under the terms of
+its license. This file is provided for attribution; it grants no rights in
+@voltro/i18n itself, which is proprietary (see LICENSE).
+
+Generated from the resolved runtime dependency closure (0 packages).
+
+---
+

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { ComponentProps } from 'react';
+import { FormattedMessage } from 'react-intl';
+import { IntlConfig } from 'react-intl';
+import { ReactNode } from 'react';
+
+/**
+ * Identity function with type narrowing. Wrap your BASE catalog in
+ * this so other locales can `extends` its key set.
+ */
+export declare const defineCatalog: <T extends MessageCatalog>(catalog: T) => T;
+
+/**
+ * Curried helper: pin the base catalog's key set, then accept a
+ * locale catalog that MUST mirror it exactly. Use for non-base
+ * locale files.
+ *
+ * The parameter is the FIXED mapped type `{ [K in keyof TBase]: string }`
+ * (not a type parameter inferred from the argument) so a directly-passed
+ * object literal is excess-property-checked: a MISSING key fails the
+ * required-property check, an EXTRA key fails the excess-property check —
+ * parity is enforced in both directions at compile time.
+ */
+export declare const defineLocale: <TBase extends MessageCatalog>() => (catalog: { readonly [K in keyof TBase]: string; }) => { readonly [K in keyof TBase]: string; };
+
+export declare const I18nProvider: ({ locale, messages, defaultLocale, silenceMissingTranslations, intlConfig, children, }: I18nProviderProps) => ReactNode;
+
+declare interface I18nProviderProps {
+    readonly locale: string;
+    readonly messages: MessageCatalog;
+    /** Base locale that owns the source-of-truth catalog. react-intl
+     *  uses this for fallback formatting + as the "this is the
+     *  reference shape" marker. */
+    readonly defaultLocale: string;
+    /** Suppress react-intl's missing-translation console error for
+     *  non-base locales. Defaults to true — during translation
+     *  rollout missing strings will fall back to the source-of-truth
+     *  locale, no need to flood the console. */
+    readonly silenceMissingTranslations?: boolean;
+    /** Forward any other IntlProvider prop unmodified (timeZone,
+     *  formats, textComponent, …). */
+    readonly intlConfig?: Partial<Omit<IntlConfig, 'locale' | 'messages' | 'defaultLocale' | 'onError'>>;
+    readonly children: ReactNode;
+}
+
+/**
+ * Build a children-to-tree wrapper that mounts `<I18nProvider>` with
+ * the supplied locale + catalog. The framework's SSG pipeline calls
+ * this once per build and passes the returned function as
+ * `renderPageToHtml({ outerWrap })`.
+ *
+ * For a multi-locale build the SSG emits per-locale HTML variants:
+ * `voltro build` calls this once per locale and, for each rendered
+ * page, picks `localeWraps.get(renderLocale)` — a `[locale]/…` route
+ * renders under its own `locale` param, a bare-path route under the
+ * `defaultLocale`. The client still swaps to the user's locale on
+ * hydration via the runtime's provider in `.framework/app.tsx`, but the
+ * emitted HTML is already locale-correct (right catalog + `meta({ locale })`).
+ */
+export declare const makeSsgWrap: (locale: string, messages: MessageCatalog, defaultLocale: string) => ((children: ReactNode) => ReactNode);
+
+export declare type MessageCatalog = Readonly<Record<string, string>>;
+
+export declare const T: ({ id, ...rest }: TProps) => ReactNode;
+
+declare type TProps = Omit<ComponentProps<typeof FormattedMessage>, 'id'> & {
+    readonly id: string;
+};
+
+export declare const useLocale: () => string;
+
+export declare const useT: (id: string, values?: Record<string, string | number | boolean | Date | null | undefined>) => string;
+
+/**
+ * Function-form translator. Unlike `useT(id, values)` which returns
+ * a string immediately, this returns a callable `(id, values) =>
+ * string` so a component can capture it once and reuse it inside
+ * conditional branches, list maps, helper components, etc. Avoids
+ * the boilerplate of N `useIntl()` calls per render — react-intl
+ * runs once, the closure replays.
+ *
+ *     const t = useTFn()
+ *     // ... inside JSX or helpers:
+ *     t('webhooks.title')
+ *     t('webhooks.subscribe.field.event')
+ *     t('webhooks.target.action.repin', { v: 2 })
+ */
+export declare const useTFn: () => (id: string, values?: Record<string, string | number | boolean | Date | null | undefined>) => string;
+
+export { }

package/dist/index.js

@@ -0,0 +1,31 @@
+import { FormattedMessage as e, IntlProvider as t, useIntl as n } from "react-intl";
+import { jsx as r } from "react/jsx-runtime";
+import { createElement as i, useCallback as a } from "react";
+//#region src/provider.tsx
+var o = ({ locale: e, messages: n, defaultLocale: i, silenceMissingTranslations: a = !0, intlConfig: o, children: s }) => {
+	let c = a ? (e) => {
+		e.code !== "MISSING_TRANSLATION" && console.error(e);
+	} : void 0;
+	return /* @__PURE__ */ r(t, {
+		locale: e,
+		defaultLocale: i,
+		messages: n,
+		...c ? { onError: c } : {},
+		...o,
+		children: s
+	});
+}, s = ({ id: t, ...n }) => /* @__PURE__ */ r(e, {
+	id: t,
+	...n
+}), c = (e, t) => n().formatMessage({ id: e }, t), l = () => n().locale, u = () => {
+	let e = n();
+	return a((t, n) => e.formatMessage({ id: t }, n), [e]);
+}, d = (e) => e, f = () => (e) => e, p = (e, t, n) => (r) => i(o, {
+	locale: e,
+	messages: t,
+	defaultLocale: n,
+	silenceMissingTranslations: !0,
+	children: r
+});
+//#endregion
+export { o as I18nProvider, s as T, d as defineCatalog, f as defineLocale, p as makeSsgWrap, l as useLocale, c as useT, u as useTFn };

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+export declare const resolveLocale: (args: ResolveLocaleArgs) => string;
+
+export declare interface ResolveLocaleArgs {
+    /** Raw `Cookie:` request header, or null/undefined when absent. */
+    readonly cookieHeader?: string | null;
+    /** Raw `Accept-Language:` request header, or null/undefined when
+     *  absent. Parsed per RFC 4647: each entry `tag;q=weight`, sorted
+     *  by descending weight, default weight 1.0. */
+    readonly acceptLanguageHeader?: string | null;
+    /** Locale codes the app actually ships catalogs for. The returned
+     *  locale is guaranteed to be one of these. */
+    readonly supported: ReadonlyArray<string>;
+    /** Last-resort fallback when no signal matches a supported locale.
+     *  MUST be in `supported`. */
+    readonly defaultLocale: string;
+}
+
+export { }

package/dist/server.js

@@ -0,0 +1,43 @@
+//#region src/server.ts
+var e = (e) => RegExp(`(?:^|;\\s*)${e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=([^;]*)`), t = (t, n) => {
+	if (!t) return;
+	let r = t.match(e(n));
+	return r ? decodeURIComponent(r[1]) : void 0;
+}, n = (e, t) => {
+	let n = e.toLowerCase();
+	for (; n.length > 0;) {
+		let e = t.find((e) => e.toLowerCase() === n);
+		if (e) return e;
+		let r = n.lastIndexOf("-");
+		if (r < 0) return;
+		n = n.slice(0, r);
+	}
+}, r = (e) => e ? e.split(",").map((e) => {
+	let [t, ...n] = e.split(";").map((e) => e.trim());
+	if (!t || t === "*") return null;
+	let r = 1;
+	for (let e of n) {
+		let t = e.match(/^q=([0-9.]+)$/i);
+		if (t) {
+			let e = Number(t[1]);
+			Number.isFinite(e) && (r = e);
+		}
+	}
+	return {
+		tag: t,
+		q: r
+	};
+}).filter((e) => e !== null).sort((e, t) => t.q - e.q) : [], i = (e) => {
+	let { cookieHeader: i, acceptLanguageHeader: a, supported: o, defaultLocale: s } = e, c = t(i, "voltro:lang");
+	if (c) {
+		let e = n(c, o);
+		if (e) return e;
+	}
+	for (let e of r(a)) {
+		let t = n(e.tag, o);
+		if (t) return t;
+	}
+	return s;
+};
+//#endregion
+export { i as resolveLocale };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@voltro/i18n",
+  "version": "0.1.0",
+  "description": "Voltro's i18n layer — thin opinionated wrap over react-intl. Provides the framework's locale-resolution conventions (voltro:lang cookie + Accept-Language fallback), a typed message-catalog helper, and a slim provider component. Power users can import directly from react-intl for advanced APIs.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-intl": "^10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}