npm - @daanvandenbergh/i18nkit - Versions diffs - 1.0.0 - Mend

@daanvandenbergh/i18nkit 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/README.md +285 -0
package/dist/i18n/catalog.d.ts +18 -0
package/dist/i18n/catalog.js +17 -0
package/dist/i18n/detect.d.ts +34 -0
package/dist/i18n/detect.js +62 -0
package/dist/i18n/i18n.d.ts +178 -0
package/dist/i18n/i18n.js +254 -0
package/dist/i18n/index.d.ts +11 -0
package/dist/i18n/index.js +10 -0
package/dist/i18n/routing.d.ts +112 -0
package/dist/i18n/routing.js +157 -0
package/dist/i18n/translate.d.ts +26 -0
package/dist/i18n/translate.js +28 -0
package/dist/i18n/types.d.ts +155 -0
package/dist/i18n/types.js +11 -0
package/dist/index.d.ts +6 -0
package/dist/index.js +6 -0
package/dist/react/LanguagePicker.d.ts +21 -0
package/dist/react/LanguagePicker.js +70 -0
package/dist/react/LocaleLink.d.ts +21 -0
package/dist/react/LocaleLink.js +23 -0
package/dist/react/flags.d.ts +21 -0
package/dist/react/flags.js +348 -0
package/dist/react/index.d.ts +10 -0
package/dist/react/index.js +10 -0
package/dist/react/provider.d.ts +58 -0
package/dist/react/provider.js +94 -0
package/dist/react/styles.css +150 -0
package/package.json +77 -0
package/skills/i18nkit-add-locale/SKILL.md +182 -0
package/skills/i18nkit-add-locale/reference/translation-rules.md +207 -0
package/skills/i18nkit-add-locale/scripts/scan.sh +148 -0
package/skills/i18nkit-sweep/SKILL.md +208 -0
package/skills/i18nkit-sweep/reference/rules.md +174 -0
package/skills/i18nkit-sweep/scripts/find_candidates.sh +99 -0

package/dist/i18n/types.d.ts ADDED Viewed

@@ -0,0 +1,155 @@
+/**
+ * The pure type core of i18nkit. Every user-facing string is a {@link LanguageText} (static)
+ * or a {@link LanguageTextFn} (parameterized): an object with exactly one entry per locale in
+ * the caller's locale union `L`. Because these are mapped types over `L`, adding a locale to
+ * an {@link I18n} instance's config grows `L`, which turns every catalog entry still missing
+ * that locale into a compile error - that is the whole point: 100% type-safe coverage.
+ *
+ * This file has zero imports (no `react`, no `node:*`) so it can be shared by server, client,
+ * and edge code alike.
+ */
+/**
+ * The URL scheme for the default locale:
+ * - `"prefix-except-default"` (the default): the default locale is served at bare URLs
+ *   (`/pricing`) and every other locale under its `htmlLang` prefix (`/nl/pricing`).
+ * - `"prefix-all"`: every locale, including the default, carries its prefix (`/en/pricing`,
+ *   `/nl/pricing`), so there is no bare-URL locale.
+ */
+export type RoutingStrategy = "prefix-except-default" | "prefix-all";
+/**
+ * Static metadata describing one locale - used to render the picker, set `<html lang>`, and
+ * pick an `Intl` formatting locale. This is configuration, not translated UI copy.
+ *
+ * The locale's own key in the config map (e.g. `"en"`) is its code; `htmlLang` and `locale`
+ * default to that key so a BCP-47-keyed config can omit them entirely.
+ */
+export interface LocaleInfo {
+    /**
+     * The locale's own name (endonym) shown in the picker in every UI language alike (e.g.
+     * "English", "Nederlands"). A plain string on purpose - a language's name is not itself translated.
+     */
+    label: string;
+    /**
+     * BCP-47 primary subtag for the document `<html lang>` attribute and the URL prefix (e.g.
+     * "en"). Defaults to the locale's key in the config map.
+     */
+    htmlLang?: string | undefined;
+    /**
+     * Full BCP-47 locale for `Intl` date/number formatting (e.g. "en-GB" -> "12 Jan 2026";
+     * "nl-NL" -> "12 jan 2026"). Defaults to {@link htmlLang}, then the locale's key. Kept
+     * separate from {@link htmlLang} because the document tag is primary-subtag only while
+     * formatting needs a concrete regional convention.
+     */
+    locale?: string | undefined;
+}
+/**
+ * A fully-resolved locale entry: {@link LocaleInfo} with its `code` and with `htmlLang`/`locale`
+ * filled in from their defaults. This is the shape exposed on an {@link I18n}'s `locales` map and
+ * `list` array, so consumers (the picker, routing) always read concrete values.
+ *
+ * @typeParam L - the locale union this entry belongs to.
+ */
+export interface ResolvedLocale<L extends string> {
+    /** The locale code (the key this entry had in the config map). */
+    code: L;
+    /** The endonym label, copied from {@link LocaleInfo.label}. */
+    label: string;
+    /** The resolved BCP-47 `<html lang>` / URL-prefix subtag (never undefined). */
+    htmlLang: string;
+    /** The resolved full BCP-47 `Intl` formatting locale (never undefined). */
+    locale: string;
+}
+/**
+ * The configuration object passed to `new I18n(...)`. The locale union `L` is inferred from the
+ * keys of {@link I18nConfig.locales}; `default` is wrapped in `NoInfer` so it never widens `L`.
+ *
+ * @typeParam L - the locale union, inferred from `locales`' keys.
+ */
+export interface I18nConfig<L extends string> {
+    /**
+     * The supported locales, keyed by their code, in the order the picker should list them
+     * (insertion order is preserved). The set of keys defines the locale union `L`.
+     */
+    locales: Record<L, LocaleInfo>;
+    /**
+     * The fallback locale for detection/resolution: used when a cookie value or `Accept-Language`
+     * is missing, invalid, or unrecognized. It is not a per-key translation fallback - the catalog
+     * types require a string for every locale, so a translation is never missing at runtime.
+     */
+    default: NoInfer<L>;
+    /**
+     * Name of the cookie the picker writes and locale detection reads. Site-scoped and readable
+     * by client script (not httpOnly). Defaults to `"locale"`.
+     */
+    cookie?: string | undefined;
+    /**
+     * Absolute site origin (e.g. `"https://example.com"`) used to build absolute URLs in
+     * `hreflangAlternates`. Optional; only that helper needs it.
+     */
+    origin?: string | undefined;
+    /**
+     * Path prefixes that must never be localized (e.g. `["/api"]`), matched segment-aware so
+     * `/api` and `/api/x` are excluded but `/apis` is not. Defaults to `[]`.
+     */
+    nonLocalizedPrefixes?: readonly string[] | undefined;
+    /**
+     * The URL scheme for the default locale (see {@link RoutingStrategy}). `"prefix-except-default"`
+     * serves the default locale at bare URLs; `"prefix-all"` prefixes every locale including the
+     * default. Defaults to `"prefix-except-default"`.
+     */
+    strategy?: RoutingStrategy | undefined;
+}
+/**
+ * A static piece of user-facing text: exactly one string per locale in `L`.
+ *
+ * @typeParam L - the locale union every key must cover.
+ * @example { en: "Answer my first call free", nl: "Beantwoord mijn eerste oproep gratis" }
+ */
+export type LanguageText<L extends string> = {
+    readonly [K in L]: string;
+};
+/**
+ * A parameterized piece of user-facing text: one builder function per locale in `L`. Use this
+ * wherever a string interpolates a runtime value, so each locale keeps control of word order.
+ *
+ * @typeParam L - the locale union every key must cover.
+ * @typeParam A - the builder's argument tuple (inferred at the call site).
+ * @example { en: (name: string) => `Good morning, ${name}`, nl: (name: string) => `Goedemorgen, ${name}` }
+ */
+export type LanguageTextFn<L extends string, A extends readonly unknown[]> = {
+    readonly [K in L]: (...args: A) => string;
+};
+/**
+ * The shape a co-located copy catalog is constrained to, so TypeScript forces every entry to
+ * carry all locale keys of `L` while each entry keeps its precise literal type (needed for
+ * argument inference in a {@link Translator}). The `readonly never[]` argument keeps the
+ * function arm contravariant, so any parameterized builder satisfies the constraint.
+ *
+ * @typeParam L - the locale union every entry must cover.
+ */
+export type LanguageTextCatalog<L extends string> = Record<string, LanguageText<L> | LanguageTextFn<L, readonly never[]>>;
+/**
+ * A translate function bound to one locale. Overloaded so the same call resolves both static and
+ * parameterized text:
+ * - `translate(text)` for a {@link LanguageText} -> the string.
+ * - `translate(text, ...args)` for a {@link LanguageTextFn} -> the built string.
+ *
+ * @typeParam L - the locale union the text objects are keyed by.
+ */
+export interface Translator<L extends string> {
+    /**
+     * Resolve a static text to its string for the bound locale.
+     *
+     * @param text - the {@link LanguageText} to resolve.
+     * @returns the string for the bound locale.
+     */
+    (text: LanguageText<L>): string;
+    /**
+     * Resolve a parameterized text, applying the arguments its per-locale builder expects.
+     *
+     * @param text - the {@link LanguageTextFn} to resolve.
+     * @param args - the arguments its builder expects.
+     * @returns the built string for the bound locale.
+     */
+    <A extends readonly unknown[]>(text: LanguageTextFn<L, A>, ...args: A): string;
+}

package/dist/i18n/types.js ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * The pure type core of i18nkit. Every user-facing string is a {@link LanguageText} (static)
+ * or a {@link LanguageTextFn} (parameterized): an object with exactly one entry per locale in
+ * the caller's locale union `L`. Because these are mapped types over `L`, adding a locale to
+ * an {@link I18n} instance's config grows `L`, which turns every catalog entry still missing
+ * that locale into a compile error - that is the whole point: 100% type-safe coverage.
+ *
+ * This file has zero imports (no `react`, no `node:*`) so it can be shared by server, client,
+ * and edge code alike.
+ */
+export {};

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+/**
+ * Package entry point (`@daanvandenbergh/i18nkit`). Exposes the framework-agnostic i18n core: the
+ * `I18n` class plus its types and helpers. React components live in the
+ * `@daanvandenbergh/i18nkit/react` subpath.
+ */
+export * from "./i18n/index.js";

package/dist/index.js ADDED Viewed

@@ -0,0 +1,6 @@
+/**
+ * Package entry point (`@daanvandenbergh/i18nkit`). Exposes the framework-agnostic i18n core: the
+ * `I18n` class plus its types and helpers. React components live in the
+ * `@daanvandenbergh/i18nkit/react` subpath.
+ */
+export * from "./i18n/index.js";

package/dist/react/LanguagePicker.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * Props for {@link LanguagePicker}. All optional - `<LanguagePicker />` works out of the box.
+ */
+export interface LanguagePickerProps {
+    /** Accessible name for the trigger button. Default `"Change language"`. */
+    changeLanguageLabel?: string | undefined;
+    /** Heading shown above the locale list; pass `""` to hide it. Default `"Language"`. */
+    headingLabel?: string | undefined;
+    /** Render a flag (or any node) for a locale code, shown before its label. Default: none. */
+    renderFlag?: ((locale: string) => ReactNode) | undefined;
+    /** Extra class name added to the wrapper, for positioning/scoping. */
+    className?: string | undefined;
+}
+/**
+ * Render the language picker.
+ *
+ * @param props - see {@link LanguagePickerProps}.
+ * @returns the picker control.
+ */
+export declare function LanguagePicker({ changeLanguageLabel, headingLabel, renderFlag, className, }?: LanguagePickerProps): ReactElement;

package/dist/react/LanguagePicker.js ADDED Viewed

@@ -0,0 +1,70 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A self-contained, accessible locale dropdown: its own open state, click-away, and Escape
+ * handling, so it drops into any client surface. Reads the active locale and the locale list from
+ * the {@link I18nProvider} context and switches via {@link useSetLocale}.
+ *
+ * Framework-agnostic: it shows each locale's endonym label by default. Pass `renderFlag` to prepend
+ * a flag node per locale - use the shipped {@link localeFlag} for the built-in flag set
+ * (`renderFlag={localeFlag}`) or supply your own. A `renderFlag` that returns `null` for a locale
+ * (as `localeFlag` does for locales without a known flag) simply shows no flag for it. Style it with
+ * the shipped stylesheet (`import "@daanvandenbergh/i18nkit/styles.css"`), fully overridable through
+ * its `--i18nkit-*` CSS custom properties.
+ */
+import { useEffect, useId, useRef, useState } from "react";
+import { useI18n, useLocale, useSetLocale } from "./provider.js";
+/**
+ * Render the language picker.
+ *
+ * @param props - see {@link LanguagePickerProps}.
+ * @returns the picker control.
+ */
+export function LanguagePicker({ changeLanguageLabel = "Change language", headingLabel = "Language", renderFlag, className, } = {}) {
+    const i18n = useI18n();
+    const locale = useLocale();
+    const setLocale = useSetLocale();
+    const [open, setOpen] = useState(false);
+    const wrapRef = useRef(null);
+    const triggerRef = useRef(null);
+    const menuId = useId();
+    // Dismiss on outside pointer-down or Escape while open. Escape returns focus to the trigger
+    // (keyboard dismissal); an outside pointer-down leaves focus wherever the user clicked.
+    useEffect(() => {
+        if (!open) {
+            return;
+        }
+        function onPointerDown(event) {
+            if (wrapRef.current && !wrapRef.current.contains(event.target)) {
+                setOpen(false);
+            }
+        }
+        function onKey(event) {
+            if (event.key === "Escape") {
+                setOpen(false);
+                triggerRef.current?.focus();
+            }
+        }
+        document.addEventListener("pointerdown", onPointerDown);
+        window.addEventListener("keydown", onKey);
+        return () => {
+            document.removeEventListener("pointerdown", onPointerDown);
+            window.removeEventListener("keydown", onKey);
+        };
+    }, [open]);
+    /** Selects a locale, closes the list, and returns focus to the trigger. */
+    function choose(code) {
+        setLocale(code);
+        setOpen(false);
+        triggerRef.current?.focus();
+    }
+    const active = i18n.locales[locale];
+    const activeLabel = active ? active.label : locale;
+    const triggerFlag = renderFlag ? renderFlag(locale) : null;
+    return (_jsxs("div", { className: className ? `i18nkit-picker ${className}` : "i18nkit-picker", ref: wrapRef, children: [_jsxs("button", { type: "button", ref: triggerRef, className: "i18nkit-picker__trigger", onClick: () => setOpen((v) => !v), "aria-label": `${changeLanguageLabel}: ${activeLabel}`, "aria-expanded": open, "aria-controls": open ? menuId : undefined, children: [triggerFlag ? _jsx("span", { className: "i18nkit-picker__flag", children: triggerFlag }) : null, _jsx("span", { className: "i18nkit-picker__current", children: activeLabel }), _jsx("svg", { className: open
+                            ? "i18nkit-picker__caret i18nkit-picker__caret--open"
+                            : "i18nkit-picker__caret", width: 10, height: 10, viewBox: "0 0 24 24", fill: "none", "aria-hidden": true, focusable: false, children: _jsx("path", { d: "M6 9l6 6 6-6", stroke: "currentColor", strokeWidth: 2.2, strokeLinecap: "round", strokeLinejoin: "round" }) })] }), open ? (_jsxs("div", { className: "i18nkit-picker__panel", id: menuId, role: "group", "aria-label": changeLanguageLabel, children: [headingLabel ? _jsx("div", { className: "i18nkit-picker__heading", children: headingLabel }) : null, i18n.list.map((info) => {
+                        const itemFlag = renderFlag ? renderFlag(info.code) : null;
+                        return (_jsxs("button", { type: "button", className: "i18nkit-picker__item", "aria-current": info.code === locale ? "true" : undefined, onClick: () => choose(info.code), children: [itemFlag ? (_jsx("span", { className: "i18nkit-picker__flag", children: itemFlag })) : null, _jsx("span", { className: "i18nkit-picker__label", children: info.label }), info.code === locale ? (_jsx("svg", { className: "i18nkit-picker__check", width: 16, height: 16, viewBox: "0 0 24 24", fill: "none", "aria-hidden": true, focusable: false, children: _jsx("path", { d: "M20 6L9 17l-5-5", stroke: "currentColor", strokeWidth: 2.4, strokeLinecap: "round", strokeLinejoin: "round" }) })) : null] }, info.code));
+                    })] })) : null] }));
+}

package/dist/react/LocaleLink.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import type { AnchorHTMLAttributes, ElementType, ReactElement } from "react";
+/**
+ * Props for {@link LocaleLink}: every standard anchor attribute (except `href`, which is
+ * localized) plus the polymorphic `as`.
+ */
+export interface LocaleLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    /** The link target, written unprefixed (e.g. `"/pricing"`); localized to the active locale. */
+    href: string;
+    /**
+     * The component to render. Defaults to `"a"`. Pass your framework's link component; it receives
+     * the localized value as its `href` prop and all other props unchanged.
+     */
+    as?: ElementType | undefined;
+}
+/**
+ * Render a locale-aware link.
+ *
+ * @param props - see {@link LocaleLinkProps}.
+ * @returns the rendered link element.
+ */
+export declare function LocaleLink({ href, as, ...rest }: LocaleLinkProps): ReactElement;

package/dist/react/LocaleLink.js ADDED Viewed

@@ -0,0 +1,23 @@
+"use client";
+/**
+ * A locale-aware link: a link written `href="/pricing"` on a `/nl/...` page renders as
+ * `/nl/pricing`, following the active locale. Localizes the href through the active
+ * {@link I18n} instance's `localizeHref`, then renders a plain `<a>` by default - or any framework
+ * link component passed via `as` (Next's `Link`, Astro's `<a>`, etc.), which receives the localized
+ * value as its `href` prop.
+ */
+import { createElement } from "react";
+import { useI18n, useLocale } from "./provider.js";
+/**
+ * Render a locale-aware link.
+ *
+ * @param props - see {@link LocaleLinkProps}.
+ * @returns the rendered link element.
+ */
+export function LocaleLink({ href, as, ...rest }) {
+    const i18n = useI18n();
+    const locale = useLocale();
+    const localized = i18n.localizeHref(href, locale);
+    const Component = as ?? "a";
+    return createElement(Component, { href: localized, ...rest });
+}

package/dist/react/flags.d.ts ADDED Viewed

@@ -0,0 +1,21 @@
+import type { ReactElement, ReactNode } from "react";
+/**
+ * The flag for a locale, drawn as a flat rounded chip - or nothing when no known flag matches.
+ *
+ * @param props.code - the locale code (e.g. `"en"`, `"pt-BR"`, `"de-CH"`).
+ * @param props.size - the rendered width in px (default 20; height is 3/4 of it).
+ * @returns the flag SVG, or `null` for an unknown locale.
+ */
+export declare function Flag({ code, size }: {
+    code: string;
+    size?: number;
+}): ReactElement | null;
+/**
+ * A ready-made `renderFlag` for {@link LanguagePicker}: `<LanguagePicker renderFlag={localeFlag} />`.
+ * Returns the built-in flag for the locale, or `null` for locales without one (the picker then
+ * shows just the label).
+ *
+ * @param locale - the locale code to draw a flag for.
+ * @returns the flag node, or `null`.
+ */
+export declare function localeFlag(locale: string): ReactNode;