@menapo/vi18n 0.0.0-stage → 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,169 @@
+import { h as Scope, m as RuntimeConfig, y as Translator } from "./types-DsdWBG0b.js";
+//#region src/server/types.d.ts
+/** Options of `handle()` and `withRequest()`. */
+interface HandleOptions {
+  /** CSP nonce for the payload `<script>` elements. */
+  nonce?: string;
+  /** Skip negotiation and use this locale (still matched against `locales`). */
+  locale?: string;
+  /** Overrides the request's zone source (cookie, `cf.timezone`, config). */
+  timeZone?: string;
+  /** Epoch ms for the scope; default `Date.now()` at request start. */
+  now?: number;
+  /**
+   * Inject the `#__vi18n` payload into HTML. Default: true, except under a
+   * `registerCatalogs()` registration, which has no client build to read it.
+   */
+  payload?: boolean;
+}
+/** Where `negotiate()` found the locale. `header-x` is the `x-vi18n-locale` request header. */
+type NegotiationSource = "url" | "referer" | "header-x" | "cookie" | "header" | "default";
+interface NegotiateResult {
+  locale: string;
+  source: NegotiationSource;
+  /**
+   * The request header the answer depends on, for the response's `Vary`
+   * (`handle()` adds it); absent when it depends on none, as when the URL
+   * decided. `Accept-Language` means the visitor's cookie or languages were
+   * read, or the root was negotiated: such a response must also be
+   * `Cache-Control: private`, since shared caches do not vary on the cookie
+   * (`handle()` sets both).
+   */
+  vary?: "x-vi18n-locale" | "Referer" | "Accept-Language";
+  /**
+   * Present for the canonical 301 (`/en/about` → `/about` under
+   * `prefix_except_default`; with `routing.paths` also `/de/about` →
+   * `/de/ueber-uns`, and with `routing.domains` a locale prefixed on another
+   * locale's host → its own host) and, with `routing.redirectRoot`, for `/`.
+   * Another host is always one `routing.domains` lists.
+   */
+  redirect?: URL;
+  /** HTTP status of `redirect`: 301 for canonicalisation, 307 for the root redirect. */
+  status?: 301 | 307;
+}
+interface AlternateLink {
+  rel: "alternate" | "canonical";
+  hreflang?: string;
+  href: string;
+}
+interface AlternateMeta {
+  property: "og:locale" | "og:locale:alternate";
+  /** `ll_TT` form, e.g. `pt_BR`. */
+  content: string;
+}
+/** `alternates(url)`: every locale + `x-default` + self-canonical, and `og:locale` metadata. */
+interface Alternates {
+  links: AlternateLink[];
+  meta: AlternateMeta[];
+}
+/** Options of `withLocale()` and `createTranslator()`. */
+interface TranslatorOptions {
+  timeZone?: string;
+  now?: number;
+}
+/** Second argument of `registerCatalogs()`. */
+interface RegisterCatalogsOptions {
+  /**
+   * `config.json` from `vi18n compile --out`, a {@link RuntimeConfig}. Typed
+   * `unknown` because it usually arrives from a JSON import; it is validated.
+   */
+  config: unknown;
+  /**
+   * `sources.json` from `vi18n compile --out` (a module namespace or the plain
+   * object). Loading starts at registration; scopes open only after it settled.
+   */
+  sources?: () => Promise<unknown>;
+}
+//#endregion
+//#region src/server/als.d.ts
+/** Framework request stores (SvelteKit `getRequestEvent()`) supply the scope; null removes it. */
+export declare function setScopeResolver(resolve: (() => Scope | undefined) | null): void;
+/**
+ * The current scope. A `withLocale`/`createTranslator` scope entered inside
+ * a request outranks the framework's request store: the store would still
+ * name the request, and an e-mail rendered for another user inside it must
+ * use that user's locale. Otherwise the resolver wins over the ALS, as
+ * frameworks may run render code outside the async context `handle` opened.
+ */
+export declare function getScope(): Scope | undefined;
+//#endregion
+//#region src/server/handle.d.ts
+/**
+ * Negotiates the locale, answers the canonical or root redirect, renders
+ * `next(request)` (the original request: rewriting stays with the router)
+ * inside the request scope, and streams HTML through the injection.
+ */
+export declare function handle(request: Request, next: (request: Request) => Response | Promise<Response>, options?: HandleOptions): Promise<Response>;
+/**
+ * Runs `fn` in the request's scope, for servers that build the response
+ * themselves (Nuxt), and returns its value; a `Response` with a body comes
+ * back with the same status, headers and bytes, its body read inside the
+ * scope.
+ */
+export declare function withRequest<T>(request: Request, fn: () => T | Promise<T>, options?: HandleOptions): Promise<Awaited<T>>;
+/**
+ * Re-scopes the current request to `locale` (Astro server islands whose
+ * props carry it). The scope object is updated in place, so the request's
+ * resolver, its payload and its `<html>` attributes all follow.
+ */
+export declare function scopeLocale(locale: string): Promise<void>;
+//#endregion
+//#region src/server/negotiate.d.ts
+/**
+ * The locale `request` would render in, the redirect `handle()` would
+ * answer, and the header its response varies on.
+ */
+export declare function negotiate(request: Request): NegotiateResult;
+//#endregion
+//#region src/server/payload.d.ts
+/**
+ * The payload element for HTML-string hooks (Nuxt `render:html`), with its
+ * preload links under `ssr.payload: "preload"`: the ids rendered so far in
+ * the current request scope, or "" when there are none.
+ * After it, `handle()` only adds late payloads for ids recorded later.
+ */
+export declare function payload(options?: {
+  nonce?: string;
+}): string;
+/** `<html lang dir>` for the current scope. */
+export declare function htmlAttributes(): {
+  lang: string;
+  dir: "ltr" | "rtl";
+};
+//#endregion
+//#region src/server/seo.d.ts
+/**
+ * hreflang links for every locale plus `x-default` (the source locale's
+ * URL), the self-canonical (`origin + pathname`: queries and fragments are
+ * not separate pages), and `og:locale` metadata for the current locale.
+ */
+export declare function alternates(url: URL): Alternates;
+/**
+ * Every path in every advertised locale, for prerender entry lists. Paths are
+ * base-free, as for `/config`'s `localizedPaths` and `localizedParams`:
+ * prerenderers list routes, and one helper must not need different input
+ * at build time and at request time (PLAN §4).
+ */
+export declare function localizedPaths(paths: readonly string[]): string[];
+/**
+ * Astro `getStaticPaths()` params for a `[...lang]` route: the locale segment
+ * of each advertised locale, `undefined` where the locale's URL carries none
+ * (the source locale under `prefix_except_default`).
+ */
+export declare function localizedParams(key?: string): {
+  params: Record<string, string | undefined>;
+}[];
+//#endregion
+//#region src/server/catalogs.d.ts
+export declare function registerCatalogs(loaders: Record<string, () => Promise<unknown>>, options: RegisterCatalogsOptions): void;
+//#endregion
+//#region src/server/translator.d.ts
+/**
+ * Runs `fn` with `t` and `fmt` bound to `locale` (and the zone in `options`),
+ * also inside a request: an e-mail for another user renders in theirs.
+ */
+export declare function withLocale<T>(locale: string, fn: () => T | Promise<T>, options?: TranslatorOptions): Promise<Awaited<T>>;
+/** `t`, `rich*` and `fmt` bound to one locale and zone, for code that cannot run inside a scope. */
+export declare function createTranslator(locale: string, options?: TranslatorOptions): Promise<Translator>;
+//#endregion
+export type { Alternates, HandleOptions, NegotiateResult, NegotiationSource, RegisterCatalogsOptions, RuntimeConfig, Scope, Translator, TranslatorOptions };