@sonenta/astro 0.1.0

package/CONTRACT.md

@@ -0,0 +1,85 @@
+# @sonenta/astro — API contract & forward-compatibility
+
+This document is the binding contract for the package's public surface. v0.1
+ships as a **standalone** integration (no dependency on the future shared i18n
+engine); the contract here is frozen so the move onto `@sonenta/i18n-core`
+(`0.2.0`) is a **non-breaking, additive** internal refactor.
+
+## Trajectory
+
+| Version | What it is |
+| --- | --- |
+| **0.1.0** | Standalone. Build-time CDN fetch + string resolution + `{var}` interpolation + source-language fallback. Pure SSG, zero client JS. |
+| **0.2.0** | Internals swapped to `@sonenta/i18n-core`. Adds CLDR plurals, accessibility surfaces (`t.aria`/`t.alt`), responsive variants, BCP-47 variant→base inheritance, and optional SSR/hybrid — all **additive**. The 0.1 API keeps working unchanged. |
+| **1.0.0** | Promoted to stable once the demos / website have validated parity. |
+
+## Frozen public surface (will not break across 0.x → 1.0)
+
+### Default export — the integration
+
+```ts
+import sonenta from "@sonenta/astro";
+sonenta(options: SonentaI18nOptions): AstroIntegration
+```
+
+### Configuration keys (`SonentaI18nOptions`)
+
+`project`, `version`, `locales`, `defaultLocale`, `fallbackLng`, `namespaces`,
+`cdnBase`, `apiBase`, `fetchImpl`.
+
+These names are **identical to what `@sonenta/i18n-core` consumes**, so the
+0.2.0 refactor reads the same config. New optional keys may be **added** (e.g.
+`surface`, `mode: "ssg" | "hybrid"`); existing keys never change meaning or
+type.
+
+### Virtual module `sonenta:i18n`
+
+```ts
+export const getT: (locale: Locale) => TFn;       // t(key, vars?) => string
+export const locales: Locale[];
+export const defaultLocale: Locale;
+export const getCatalog: (locale, namespace?) => Record<string, unknown> | null;
+export default i18n: SonentaI18n;
+```
+
+`getT(locale)` returns a `t()` whose **call signature is frozen**:
+`t(key: string, vars?: Record<string, string | number>): string`. The 0.2.0
+release **adds methods** to the returned function (e.g. `t.aria(key)`,
+`t.alt(key)`, plural-aware `t(key, { count })`) — additive, never breaking the
+bare `t(key)` call.
+
+### Runtime entry `@sonenta/astro/runtime`
+
+`createSonentaI18n(options)`, `createT(...)`, `fetchAll`/`fetchBundle`/
+`fetchNamespace`, `buildBundleUrl`, `resolveCdnBase`, and all types. Stable.
+
+### CDN wire layout (owned by backend, consumed here)
+
+`{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`
+
+- `200` → bundle JSON.
+- `404` → treated as **absent** (`null`); the locale falls back to the source.
+- any other non-OK / transport error → **throws** (a misconfigured build fails
+  loudly rather than silently shipping empty pages).
+
+## v0.1 explicit non-goals (deliberately deferred to the core-backed release)
+
+To guarantee the additive path above, v0.1 ships **no naive implementation** of
+the following — there is therefore no v0.1 behaviour to break when core takes
+over their semantics:
+
+- **CLDR plurals** (`t(key, { count })` pluralization).
+- **Accessibility surfaces** (`t.aria`, `t.alt`, screen-reader / plain-language
+  variants).
+- **Responsive surface variants** (desktop / mobile / tablet overlays).
+- **BCP-47 variant→base inheritance** (`fr-CA → fr`). v0.1 applies the
+  configured `fallbackLng` list literally.
+- **SSR / hybrid** request-scoped resolution. v0.1 is build-time SSG only.
+
+## Boundaries
+
+- Backend owns the API/CDN wire contract; this package is a **consumer** and
+  never changes it. Contract questions route through the SDK owner.
+- Add-on SDKs (`feedback`, `realtime`, `in-context`) are runtime/DOM and run
+  only inside Astro **client islands** (via the React bindings), never in
+  static `.astro` output.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verbumia
+
+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,133 @@
+# @sonenta/astro
+
+Official [Astro](https://astro.build) integration for [Sonenta](https://sonenta.com) i18n.
+
+Your translations live in Sonenta; this integration pulls the released bundles
+from the CDN **at build time** and inlines them into your static HTML. There is
+**zero client-side JavaScript** — it's pure SSG, the way Astro content sites
+want i18n to work.
+
+```sh
+npm install @sonenta/astro
+# or: pnpm add @sonenta/astro   /   yarn add @sonenta/astro
+```
+
+> **v0.1 — standalone.** This release does string resolution, `{var}`
+> interpolation, and source-language fallback. CLDR plurals, accessibility
+> surfaces, and responsive variants arrive **additively** in `0.2.0` (backed by
+> `@sonenta/i18n-core`) **without any breaking change** to the API below — see
+> [CONTRACT.md](./CONTRACT.md).
+
+## Quick start
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import sonenta from "@sonenta/astro";
+
+export default defineConfig({
+  // Astro's native i18n routing — the integration reads Astro.currentLocale.
+  i18n: { defaultLocale: "fr", locales: ["fr", "en", "es"] },
+  integrations: [
+    sonenta({
+      project: "your-project-uuid",   // from your Sonenta dashboard
+      locales: ["fr", "en", "es"],
+      defaultLocale: "fr",
+      namespaces: ["common"],
+    }),
+  ],
+});
+```
+
+```astro
+---
+// src/pages/index.astro
+import { getT, defaultLocale } from "sonenta:i18n";
+
+const t = getT(Astro.currentLocale ?? defaultLocale);
+---
+<html lang={Astro.currentLocale ?? defaultLocale}>
+  <head><title>{t("home.title")}</title></head>
+  <body>
+    <h1>{t("home.title")}</h1>
+    <p>{t("home.greeting", { name: "Ada" })}</p>
+  </body>
+</html>
+```
+
+That's it. `astro build` fetches `common.json` for every locale and freezes the
+strings into the page. Nothing ships to the browser.
+
+## The `sonenta:i18n` virtual module
+
+The integration exposes a virtual module you can import from any `.astro` file
+(or `.ts`/`.js` run at build time):
+
+| Export | Description |
+| --- | --- |
+| `getT(locale)` | Returns a `t(key, vars?)` bound to `locale`. |
+| `locales` | The locales fetched into the build. |
+| `defaultLocale` | The resolved source/default locale. |
+| `getCatalog(locale, ns?)` | Raw fetched dictionary, or `null` if absent. |
+
+TypeScript types for the virtual module are injected automatically (Astro's
+`injectTypes`), so `getT` is fully typed with no extra config.
+
+### Key resolution
+
+- **Dotted keys** walk nested objects: `t("home.cta.label")`.
+- **Namespaces** use the i18next-style `ns:key` syntax: `t("docs:intro")`.
+  Un-prefixed keys resolve against the first namespace (default `"common"`).
+- **Interpolation**: `t("greeting", { name: "Ada" })` replaces `{name}`.
+  Unknown placeholders are left intact.
+- **Fallback**: a missing key falls back through `fallbackLng` (default: the
+  source locale). A locale whose bundle is absent (e.g. plan-limit) falls back
+  the same way. Still missing everywhere → the raw key is returned (i18next
+  parity).
+
+## Without the integration (explicit build-time fetch)
+
+Prefer an explicit top-level `await`? Use the runtime directly — no virtual
+module, no Vite plugin:
+
+```ts
+// src/i18n.ts
+import { createSonentaI18n } from "@sonenta/astro/runtime";
+
+export const i18n = await createSonentaI18n({
+  project: "your-project-uuid",
+  locales: ["fr", "en", "es"],
+  defaultLocale: "fr",
+});
+export const getT = i18n.getT;
+```
+
+## Configuration
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `project` | `string` | — | **Required.** Project UUID. |
+| `locales` | `string[]` | — | **Required.** Locales to fetch + freeze. |
+| `version` | `string` | `"main"` | Released version slug / pinned hash. |
+| `defaultLocale` | `string` | `locales[0]` | Source / fallback locale. |
+| `fallbackLng` | `string \| string[]` | `[defaultLocale]` | Missing-key fallback chain. |
+| `namespaces` | `string[]` | `["common"]` | Bundle files; first is the default ns. |
+| `cdnBase` | `string` | `https://cdn.sonenta.com` | CDN host (no `/p`). Env: `SONENTA_CDN_BASE`. |
+| `apiBase` | `string` | `https://api.sonenta.dev` | Reserved (forward-compat). |
+| `fetchImpl` | `typeof fetch` | global `fetch` | Custom fetch (runtime API only). |
+
+Bundles are fetched from
+`{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json` — the same
+CDN layout as `@sonenta/react-i18next`.
+
+## Notes & limits (v0.1)
+
+- **Add-ons are island-only.** `@sonenta/feedback`, `@sonenta/realtime`, and
+  `@sonenta/in-context` are runtime/DOM SDKs — they run inside Astro client
+  islands (reusing the React bindings), not in static `.astro` output.
+- **SSR/hybrid** is not yet wired; v0.1 is build-time SSG. A request-scoped
+  resolver (fetch-cache + revalidate) arrives with the core-backed release.
+
+## License
+
+MIT © Sonenta

package/dist/chunk-CK2DAB6G.js

@@ -0,0 +1,131 @@
+// src/types.ts
+var DEFAULT_CDN_BASE = "https://cdn.sonenta.com";
+var DEFAULT_VERSION = "main";
+var DEFAULT_NAMESPACE = "common";
+
+// src/cdn.ts
+function trimSlashes(s) {
+  return s.replace(/\/+$/, "");
+}
+function resolveCdnBase(opts) {
+  const env = typeof process !== "undefined" ? process.env?.SONENTA_CDN_BASE : void 0;
+  return trimSlashes(opts.cdnBase ?? env ?? DEFAULT_CDN_BASE);
+}
+function buildBundleUrl(opts, locale, namespace) {
+  const base = resolveCdnBase(opts);
+  const version = opts.version ?? DEFAULT_VERSION;
+  return `${base}/p/${opts.project}/${version}/latest/${locale}/${namespace}.json`;
+}
+async function fetchBundle(opts, locale, namespace) {
+  const url = buildBundleUrl(opts, locale, namespace);
+  const doFetch = opts.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await doFetch(url, { method: "GET" });
+  } catch (e) {
+    throw new Error(
+      `[@sonenta/astro] CDN fetch failed for ${locale}/${namespace}: ${e.message}`
+    );
+  }
+  if (!res.ok) {
+    if (res.status === 404) return null;
+    throw new Error(`[@sonenta/astro] CDN ${res.status} on ${url}`);
+  }
+  return await res.json();
+}
+async function fetchNamespace(opts, locales, namespace) {
+  const entries = await Promise.all(
+    locales.map(
+      async (l) => [l, await fetchBundle(opts, l, namespace)]
+    )
+  );
+  return Object.fromEntries(entries);
+}
+async function fetchAll(opts, locales, namespaces) {
+  const out = {};
+  for (const l of locales) out[l] = {};
+  await Promise.all(
+    locales.flatMap(
+      (l) => namespaces.map(async (ns) => {
+        out[l][ns] = await fetchBundle(opts, l, ns);
+      })
+    )
+  );
+  return out;
+}
+
+// src/resolver.ts
+function normalizeFallback(fallbackLng, defaultLocale) {
+  if (fallbackLng == null) return [defaultLocale];
+  return Array.isArray(fallbackLng) ? fallbackLng : [fallbackLng];
+}
+function splitKey(key, defaultNamespace) {
+  const i = key.indexOf(":");
+  if (i === -1) return [defaultNamespace, key];
+  return [key.slice(0, i), key.slice(i + 1)];
+}
+function walk(bundle, path) {
+  if (!bundle) return void 0;
+  let cursor = bundle;
+  for (const part of path.split(".")) {
+    if (cursor && typeof cursor === "object" && part in cursor) {
+      cursor = cursor[part];
+    } else {
+      return void 0;
+    }
+  }
+  return cursor;
+}
+function interpolate(template, vars) {
+  if (!vars) return template;
+  return template.replace(
+    /\{(\w+)\}/g,
+    (_, name) => name in vars ? String(vars[name]) : `{${name}}`
+  );
+}
+function createT(data, locale, fallbackChain, defaultNamespace) {
+  const order = [locale, ...fallbackChain.filter((l) => l !== locale)];
+  return function t(key, vars) {
+    const [ns, rest] = splitKey(key, defaultNamespace);
+    for (const l of order) {
+      const hit = walk(data[l]?.[ns], rest);
+      if (typeof hit === "string") return interpolate(hit, vars);
+    }
+    return key;
+  };
+}
+async function createSonentaI18n(options) {
+  if (!options.project) {
+    throw new Error("[@sonenta/astro] `project` (UUID) is required.");
+  }
+  if (!options.locales?.length) {
+    throw new Error("[@sonenta/astro] `locales` must be a non-empty array.");
+  }
+  const locales = options.locales;
+  const defaultLocale = options.defaultLocale ?? locales[0];
+  const namespaces = options.namespaces?.length ? options.namespaces : [DEFAULT_NAMESPACE];
+  const defaultNamespace = namespaces[0];
+  const fallbackChain = normalizeFallback(options.fallbackLng, defaultLocale);
+  const data = await fetchAll(options, locales, namespaces);
+  return {
+    locales,
+    defaultLocale,
+    getT(locale) {
+      return createT(data, locale, fallbackChain, defaultNamespace);
+    },
+    getCatalog(locale, namespace) {
+      return data[locale]?.[namespace ?? defaultNamespace] ?? null;
+    }
+  };
+}
+
+export {
+  resolveCdnBase,
+  buildBundleUrl,
+  fetchBundle,
+  fetchNamespace,
+  fetchAll,
+  createT,
+  createSonentaI18n
+};
+//# sourceMappingURL=chunk-CK2DAB6G.js.map

package/dist/chunk-CK2DAB6G.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/cdn.ts","../src/resolver.ts"],"sourcesContent":["/**\n * Public types for `@sonenta/astro` v0.1 (standalone, pre-core).\n *\n * FORWARD-COMPATIBILITY CONTRACT (frozen day-one — see CONTRACT.md): every\n * option key here is the SAME key the future `@sonenta/i18n-core`-backed\n * release will consume, so the later refactor (0.2.0) is a non-breaking,\n * additive internal swap. New capabilities (surfaces, a11y accessors, CLDR\n * plurals, variants) arrive ADDITIVELY; nothing here changes meaning.\n */\n\n/** A BCP-47 locale code, e.g. `\"fr\"`, `\"en\"`, `\"fr-CA\"`. */\nexport type Locale = string;\n\n/** A bundle namespace (the `{ns}.json` file on the CDN), e.g. `\"common\"`. */\nexport type Namespace = string;\n\n/** Interpolation variables for a `t()` call: `t(\"greeting\", { name: \"Ada\" })`. */\nexport type Vars = Record<string, string | number>;\n\n/** A resolved, per-locale translation function. */\nexport type TFn = (key: string, vars?: Vars) => string;\n\n/**\n * Configuration for the Sonenta Astro integration / runtime.\n *\n * Bundles are fetched at BUILD time from\n * `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`\n * (the canonical Sonenta CDN layout, identical to `@sonenta/react-i18next`).\n */\nexport interface SonentaI18nOptions {\n  /** Project UUID from your Sonenta dashboard. Required. */\n  project: string;\n\n  /**\n   * Released version slug or pinned content hash. Default `\"main\"`.\n   * The CDN serves the latest release of this version under `/latest/`.\n   */\n  version?: string;\n\n  /**\n   * Locales to fetch and freeze into the static build. Required, non-empty.\n   * A locale whose bundle 404s (e.g. a plan-limit-blocked language) is kept\n   * as `null` and transparently falls back to the source language.\n   */\n  locales: Locale[];\n\n  /**\n   * Source / default locale. Default = `locales[0]`. Used as the implicit\n   * final fallback target and as Astro's source language.\n   */\n  defaultLocale?: Locale;\n\n  /**\n   * Ordered fallback chain applied when a key is missing in the active\n   * locale. Default = `[defaultLocale]`. v0.1 applies these locales in\n   * order; BCP-47 variant→base inheritance (`fr-CA → fr`) is deliberately\n   * left to the core-backed release.\n   */\n  fallbackLng?: Locale | Locale[];\n\n  /**\n   * Namespaces (bundle files) to fetch. Default `[\"common\"]`. The first\n   * entry is the default namespace for un-prefixed keys; address others with\n   * the i18next-style `\"ns:key\"` syntax.\n   */\n  namespaces?: Namespace[];\n\n  /**\n   * CDN host root for translation bundles, WITHOUT the `/p` segment.\n   * Default `\"https://cdn.sonenta.com\"`. Overridable via the\n   * `SONENTA_CDN_BASE` env var (also a bare host; for local dev point it at\n   * your translation CDN). The `/p/{project}/{version}/latest/...` path is\n   * appended by the loader.\n   */\n  cdnBase?: string;\n\n  /**\n   * API host root. Reserved for forward-compatibility (the core-backed\n   * release uses it for the public language manifest and dev-mode runtime\n   * fetch). Default `\"https://api.sonenta.dev\"`. Unused by v0.1's prod\n   * build-time path.\n   */\n  apiBase?: string;\n\n  /**\n   * Injectable `fetch` implementation (testing / proxies / custom agents).\n   * Defaults to the global `fetch`.\n   */\n  fetchImpl?: typeof fetch;\n}\n\n/**\n * The resolved Sonenta i18n handle returned by `createSonentaI18n` and\n * exposed through the `sonenta:i18n` virtual module.\n */\nexport interface SonentaI18n {\n  /** Build a translation function bound to `locale`. */\n  getT(locale: Locale): TFn;\n  /** The locales that were fetched (the configured `locales`). */\n  readonly locales: Locale[];\n  /** The resolved source/default locale. */\n  readonly defaultLocale: Locale;\n  /**\n   * Raw fetched dictionary for `locale` / `namespace` (default namespace when\n   * omitted), or `null` when that bundle was absent (404 / plan-limit).\n   */\n  getCatalog(locale: Locale, namespace?: Namespace): Record<string, unknown> | null;\n}\n\n/** Default CDN host (no `/p`). */\nexport const DEFAULT_CDN_BASE = \"https://cdn.sonenta.com\";\n/** Default API host. */\nexport const DEFAULT_API_BASE = \"https://api.sonenta.dev\";\n/** Default version slug. */\nexport const DEFAULT_VERSION = \"main\";\n/** Default namespace. */\nexport const DEFAULT_NAMESPACE = \"common\";\n","/**\n * Build-time CDN loader for Sonenta translation bundles.\n *\n * Mirrors the canonical Sonenta CDN layout used by `@sonenta/react-i18next`:\n *   `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`\n *\n * Pure data fetch — no DOM, no React, no runtime. Called during `astro build`\n * so the strings inline into the static HTML (zero client JS).\n */\n\nimport {\n  DEFAULT_CDN_BASE,\n  DEFAULT_VERSION,\n  type Locale,\n  type Namespace,\n  type SonentaI18nOptions,\n} from \"./types\";\n\n/** A fetched bundle (a flat or nested dictionary of message strings). */\nexport type Bundle = Record<string, unknown>;\n\n/** Strip trailing slashes so URL joins never double up. */\nfunction trimSlashes(s: string): string {\n  return s.replace(/\\/+$/, \"\");\n}\n\n/**\n * Resolve the effective CDN host (no `/p`): explicit option wins, then the\n * `SONENTA_CDN_BASE` env var, then the production default.\n */\nexport function resolveCdnBase(opts: Pick<SonentaI18nOptions, \"cdnBase\">): string {\n  const env =\n    typeof process !== \"undefined\" ? process.env?.SONENTA_CDN_BASE : undefined;\n  return trimSlashes(opts.cdnBase ?? env ?? DEFAULT_CDN_BASE);\n}\n\n/**\n * Build the bundle URL for one `(locale, namespace)` pair.\n * `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`\n */\nexport function buildBundleUrl(\n  opts: Pick<SonentaI18nOptions, \"project\" | \"version\" | \"cdnBase\">,\n  locale: Locale,\n  namespace: Namespace,\n): string {\n  const base = resolveCdnBase(opts);\n  const version = opts.version ?? DEFAULT_VERSION;\n  return `${base}/p/${opts.project}/${version}/latest/${locale}/${namespace}.json`;\n}\n\n/**\n * Fetch a single bundle. Resolves to `null` on 404 (locale absent from the\n * project — e.g. a plan-limit-blocked language) so callers fall back to the\n * source language. Any other non-OK status or transport error throws so a\n * misconfigured build fails loudly rather than silently shipping empty pages.\n */\nexport async function fetchBundle(\n  opts: Pick<SonentaI18nOptions, \"project\" | \"version\" | \"cdnBase\" | \"fetchImpl\">,\n  locale: Locale,\n  namespace: Namespace,\n): Promise<Bundle | null> {\n  const url = buildBundleUrl(opts, locale, namespace);\n  const doFetch = opts.fetchImpl ?? fetch;\n  let res: Response;\n  try {\n    res = await doFetch(url, { method: \"GET\" });\n  } catch (e) {\n    throw new Error(\n      `[@sonenta/astro] CDN fetch failed for ${locale}/${namespace}: ${\n        (e as Error).message\n      }`,\n    );\n  }\n  if (!res.ok) {\n    if (res.status === 404) return null;\n    throw new Error(`[@sonenta/astro] CDN ${res.status} on ${url}`);\n  }\n  return (await res.json()) as Bundle;\n}\n\n/**\n * Fetch one namespace across every locale, in parallel. Absent locales map to\n * `null`. Returns `Record<Locale, Bundle | null>`.\n */\nexport async function fetchNamespace(\n  opts: Pick<\n    SonentaI18nOptions,\n    \"project\" | \"version\" | \"cdnBase\" | \"fetchImpl\"\n  >,\n  locales: Locale[],\n  namespace: Namespace,\n): Promise<Record<Locale, Bundle | null>> {\n  const entries = await Promise.all(\n    locales.map(\n      async (l) => [l, await fetchBundle(opts, l, namespace)] as const,\n    ),\n  );\n  return Object.fromEntries(entries) as Record<Locale, Bundle | null>;\n}\n\n/**\n * Fetch every `(locale, namespace)` pair. Returns a nested map keyed by\n * locale then namespace: `data[locale][namespace] = Bundle | null`.\n */\nexport async function fetchAll(\n  opts: Pick<\n    SonentaI18nOptions,\n    \"project\" | \"version\" | \"cdnBase\" | \"fetchImpl\"\n  >,\n  locales: Locale[],\n  namespaces: Namespace[],\n): Promise<Record<Locale, Record<Namespace, Bundle | null>>> {\n  const out: Record<Locale, Record<Namespace, Bundle | null>> = {};\n  for (const l of locales) out[l] = {};\n  await Promise.all(\n    locales.flatMap((l) =>\n      namespaces.map(async (ns) => {\n        out[l]![ns] = await fetchBundle(opts, l, ns);\n      }),\n    ),\n  );\n  return out;\n}\n","/**\n * Build-time translation resolver.\n *\n * v0.1 SCOPE (frozen — see CONTRACT.md): string resolution + `{var}`\n * interpolation + source-language fallback ONLY. Deliberately NO CLDR\n * plurals, NO surfaces, NO a11y accessors, NO BCP-47 variant→base\n * inheritance — those carry real i18n SEMANTICS owned by `@sonenta/i18n-core`\n * and arrive additively in 0.2.0. Keeping them out of v0.1 means there is no\n * naive semantics to break when the core swaps in underneath this same API.\n */\n\nimport { fetchAll, type Bundle } from \"./cdn\";\nimport {\n  DEFAULT_NAMESPACE,\n  type Locale,\n  type Namespace,\n  type SonentaI18n,\n  type SonentaI18nOptions,\n  type TFn,\n  type Vars,\n} from \"./types\";\n\n/** Normalize `fallbackLng` (scalar | array | undefined) into a locale list. */\nfunction normalizeFallback(\n  fallbackLng: SonentaI18nOptions[\"fallbackLng\"],\n  defaultLocale: Locale,\n): Locale[] {\n  if (fallbackLng == null) return [defaultLocale];\n  return Array.isArray(fallbackLng) ? fallbackLng : [fallbackLng];\n}\n\n/** Split an i18next-style `\"ns:key\"` into `[namespace, key]`. */\nfunction splitKey(key: string, defaultNamespace: Namespace): [Namespace, string] {\n  const i = key.indexOf(\":\");\n  if (i === -1) return [defaultNamespace, key];\n  return [key.slice(0, i), key.slice(i + 1)];\n}\n\n/** Walk a dotted path (`\"home.title\"`) through a bundle; `undefined` on miss. */\nfunction walk(bundle: Bundle | null | undefined, path: string): unknown {\n  if (!bundle) return undefined;\n  let cursor: unknown = bundle;\n  for (const part of path.split(\".\")) {\n    if (cursor && typeof cursor === \"object\" && part in cursor) {\n      cursor = (cursor as Record<string, unknown>)[part];\n    } else {\n      return undefined;\n    }\n  }\n  return cursor;\n}\n\n/** Substitute `{var}` placeholders; unknown placeholders are left intact. */\nfunction interpolate(template: string, vars?: Vars): string {\n  if (!vars) return template;\n  return template.replace(/\\{(\\w+)\\}/g, (_, name: string) =>\n    name in vars ? String(vars[name]) : `{${name}}`,\n  );\n}\n\n/**\n * Build a `t()` bound to `locale`, given the fetched data and resolution\n * order. Lookup: active locale's namespace dict → each fallback locale's same\n * namespace dict → the raw key (i18next-parity missing-key behaviour).\n */\nexport function createT(\n  data: Record<Locale, Record<Namespace, Bundle | null>>,\n  locale: Locale,\n  fallbackChain: Locale[],\n  defaultNamespace: Namespace,\n): TFn {\n  // De-duped resolution order: active locale first, then configured\n  // fallbacks (skipping the active one if it reappears).\n  const order = [locale, ...fallbackChain.filter((l) => l !== locale)];\n  return function t(key: string, vars?: Vars): string {\n    const [ns, rest] = splitKey(key, defaultNamespace);\n    for (const l of order) {\n      const hit = walk(data[l]?.[ns], rest);\n      if (typeof hit === \"string\") return interpolate(hit, vars);\n    }\n    // Missing everywhere → return the raw key (unchanged), i18next-style.\n    return key;\n  };\n}\n\n/**\n * Fetch every configured bundle at build time and return a resolved\n * {@link SonentaI18n} handle. Call once (top-level `await`) and reuse its\n * `getT(locale)` across pages.\n */\nexport async function createSonentaI18n(\n  options: SonentaI18nOptions,\n): Promise<SonentaI18n> {\n  if (!options.project) {\n    throw new Error(\"[@sonenta/astro] `project` (UUID) is required.\");\n  }\n  if (!options.locales?.length) {\n    throw new Error(\"[@sonenta/astro] `locales` must be a non-empty array.\");\n  }\n  const locales = options.locales;\n  const defaultLocale = options.defaultLocale ?? locales[0]!;\n  const namespaces =\n    options.namespaces?.length ? options.namespaces : [DEFAULT_NAMESPACE];\n  const defaultNamespace = namespaces[0]!;\n  const fallbackChain = normalizeFallback(options.fallbackLng, defaultLocale);\n\n  const data = await fetchAll(options, locales, namespaces);\n\n  return {\n    locales,\n    defaultLocale,\n    getT(locale: Locale): TFn {\n      return createT(data, locale, fallbackChain, defaultNamespace);\n    },\n    getCatalog(locale: Locale, namespace?: Namespace): Bundle | null {\n      return data[locale]?.[namespace ?? defaultNamespace] ?? null;\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.cjs

@@ -0,0 +1,252 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  buildBundleUrl: () => buildBundleUrl,
+  createSonentaI18n: () => createSonentaI18n,
+  createT: () => createT,
+  default: () => index_default,
+  fetchAll: () => fetchAll,
+  fetchBundle: () => fetchBundle,
+  fetchNamespace: () => fetchNamespace,
+  resolveCdnBase: () => resolveCdnBase,
+  sonenta: () => sonenta
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/virtual.ts
+var VIRTUAL_ID = "sonenta:i18n";
+var RESOLVED_ID = "\0sonenta:i18n";
+function serializableOptions(options) {
+  const { fetchImpl: _omit, ...rest } = options;
+  return rest;
+}
+function moduleSource(options) {
+  const opts = JSON.stringify(serializableOptions(options));
+  return [
+    `import { createSonentaI18n } from "@sonenta/astro/runtime";`,
+    `const __i18n = await createSonentaI18n(${opts});`,
+    `export const getT = (locale) => __i18n.getT(locale);`,
+    `export const locales = __i18n.locales;`,
+    `export const defaultLocale = __i18n.defaultLocale;`,
+    `export const getCatalog = (locale, ns) => __i18n.getCatalog(locale, ns);`,
+    `export default __i18n;`,
+    ``
+  ].join("\n");
+}
+function sonentaI18nVitePlugin(options) {
+  return {
+    name: "sonenta:astro-i18n",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+      return null;
+    },
+    load(id) {
+      if (id === RESOLVED_ID) return moduleSource(options);
+      return null;
+    }
+  };
+}
+
+// src/integration.ts
+var VIRTUAL_DTS = `declare module "sonenta:i18n" {
+  import type { SonentaI18n, TFn, Locale, Namespace } from "@sonenta/astro/runtime";
+  /** Translation function bound to \`locale\`. */
+  export const getT: (locale: Locale) => TFn;
+  /** Locales fetched and frozen into the build. */
+  export const locales: Locale[];
+  /** Resolved source/default locale. */
+  export const defaultLocale: Locale;
+  /** Raw fetched dictionary for a locale/namespace, or null when absent. */
+  export const getCatalog: (
+    locale: Locale,
+    namespace?: Namespace,
+  ) => Record<string, unknown> | null;
+  const i18n: SonentaI18n;
+  export default i18n;
+}
+`;
+function sonenta(options) {
+  if (!options?.project) {
+    throw new Error("[@sonenta/astro] `project` (UUID) is required.");
+  }
+  if (!options.locales?.length) {
+    throw new Error("[@sonenta/astro] `locales` must be a non-empty array.");
+  }
+  return {
+    name: "@sonenta/astro",
+    hooks: {
+      "astro:config:setup": ({ updateConfig, logger }) => {
+        if (options.fetchImpl) {
+          logger.warn(
+            "`fetchImpl` is ignored by the integration; the build uses the global fetch. Use `@sonenta/astro/runtime` directly if you need a custom fetch."
+          );
+        }
+        updateConfig({
+          vite: { plugins: [sonentaI18nVitePlugin(options)] }
+        });
+        logger.info(
+          `i18n wired for project ${options.project} (${options.locales.length} locales, build-time CDN fetch).`
+        );
+      },
+      "astro:config:done": ({ injectTypes }) => {
+        injectTypes({ filename: "sonenta-i18n.d.ts", content: VIRTUAL_DTS });
+      }
+    }
+  };
+}
+
+// src/types.ts
+var DEFAULT_CDN_BASE = "https://cdn.sonenta.com";
+var DEFAULT_VERSION = "main";
+var DEFAULT_NAMESPACE = "common";
+
+// src/cdn.ts
+function trimSlashes(s) {
+  return s.replace(/\/+$/, "");
+}
+function resolveCdnBase(opts) {
+  const env = typeof process !== "undefined" ? process.env?.SONENTA_CDN_BASE : void 0;
+  return trimSlashes(opts.cdnBase ?? env ?? DEFAULT_CDN_BASE);
+}
+function buildBundleUrl(opts, locale, namespace) {
+  const base = resolveCdnBase(opts);
+  const version = opts.version ?? DEFAULT_VERSION;
+  return `${base}/p/${opts.project}/${version}/latest/${locale}/${namespace}.json`;
+}
+async function fetchBundle(opts, locale, namespace) {
+  const url = buildBundleUrl(opts, locale, namespace);
+  const doFetch = opts.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await doFetch(url, { method: "GET" });
+  } catch (e) {
+    throw new Error(
+      `[@sonenta/astro] CDN fetch failed for ${locale}/${namespace}: ${e.message}`
+    );
+  }
+  if (!res.ok) {
+    if (res.status === 404) return null;
+    throw new Error(`[@sonenta/astro] CDN ${res.status} on ${url}`);
+  }
+  return await res.json();
+}
+async function fetchNamespace(opts, locales, namespace) {
+  const entries = await Promise.all(
+    locales.map(
+      async (l) => [l, await fetchBundle(opts, l, namespace)]
+    )
+  );
+  return Object.fromEntries(entries);
+}
+async function fetchAll(opts, locales, namespaces) {
+  const out = {};
+  for (const l of locales) out[l] = {};
+  await Promise.all(
+    locales.flatMap(
+      (l) => namespaces.map(async (ns) => {
+        out[l][ns] = await fetchBundle(opts, l, ns);
+      })
+    )
+  );
+  return out;
+}
+
+// src/resolver.ts
+function normalizeFallback(fallbackLng, defaultLocale) {
+  if (fallbackLng == null) return [defaultLocale];
+  return Array.isArray(fallbackLng) ? fallbackLng : [fallbackLng];
+}
+function splitKey(key, defaultNamespace) {
+  const i = key.indexOf(":");
+  if (i === -1) return [defaultNamespace, key];
+  return [key.slice(0, i), key.slice(i + 1)];
+}
+function walk(bundle, path) {
+  if (!bundle) return void 0;
+  let cursor = bundle;
+  for (const part of path.split(".")) {
+    if (cursor && typeof cursor === "object" && part in cursor) {
+      cursor = cursor[part];
+    } else {
+      return void 0;
+    }
+  }
+  return cursor;
+}
+function interpolate(template, vars) {
+  if (!vars) return template;
+  return template.replace(
+    /\{(\w+)\}/g,
+    (_, name) => name in vars ? String(vars[name]) : `{${name}}`
+  );
+}
+function createT(data, locale, fallbackChain, defaultNamespace) {
+  const order = [locale, ...fallbackChain.filter((l) => l !== locale)];
+  return function t(key, vars) {
+    const [ns, rest] = splitKey(key, defaultNamespace);
+    for (const l of order) {
+      const hit = walk(data[l]?.[ns], rest);
+      if (typeof hit === "string") return interpolate(hit, vars);
+    }
+    return key;
+  };
+}
+async function createSonentaI18n(options) {
+  if (!options.project) {
+    throw new Error("[@sonenta/astro] `project` (UUID) is required.");
+  }
+  if (!options.locales?.length) {
+    throw new Error("[@sonenta/astro] `locales` must be a non-empty array.");
+  }
+  const locales = options.locales;
+  const defaultLocale = options.defaultLocale ?? locales[0];
+  const namespaces = options.namespaces?.length ? options.namespaces : [DEFAULT_NAMESPACE];
+  const defaultNamespace = namespaces[0];
+  const fallbackChain = normalizeFallback(options.fallbackLng, defaultLocale);
+  const data = await fetchAll(options, locales, namespaces);
+  return {
+    locales,
+    defaultLocale,
+    getT(locale) {
+      return createT(data, locale, fallbackChain, defaultNamespace);
+    },
+    getCatalog(locale, namespace) {
+      return data[locale]?.[namespace ?? defaultNamespace] ?? null;
+    }
+  };
+}
+
+// src/index.ts
+var index_default = sonenta;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildBundleUrl,
+  createSonentaI18n,
+  createT,
+  fetchAll,
+  fetchBundle,
+  fetchNamespace,
+  resolveCdnBase,
+  sonenta
+});
+//# sourceMappingURL=index.cjs.map