@ingram-tech/nk-i18n 0.1.0

package/README.md

@@ -0,0 +1,121 @@
+# @ingram-tech/nk-i18n
+
+Type-safe, English-as-key i18n for Ingram Next.js sites. The English source text
+**is** the key (no `en.json`), translations are ICU MessageFormat, and catalogs
+are plain colocated JSON. Routing is left to the site — the translator only needs
+a locale string, so it works with URL-prefixed (`/fr/…`, `[locale]`, middleware
+rewrite) or cookieless (cookie + `Accept-Language`) setups alike.
+
+```bash
+bun add @ingram-tech/nk-i18n
+```
+
+## Locale config (one table, derived constants)
+
+```ts
+// lib/i18n/locales.ts
+import { defineI18nConfig, deriveLocaleConstants, localeMap } from "@ingram-tech/nk-i18n";
+
+export const i18nConfig = defineI18nConfig({
+	baseLocale: "en",
+	locales: {
+		en: { label: "English", htmlLang: "en", ogLocale: "en_US" },
+		fr: { label: "Français", htmlLang: "fr-BE", ogLocale: "fr_BE" },
+		nl: { label: "Nederlands", htmlLang: "nl-BE", ogLocale: "nl_BE" },
+	},
+});
+
+export type Locale = keyof typeof i18nConfig.locales & string;
+export const { SUPPORTED_LOCALES, DEFAULT_LOCALE, LOCALE_NAMES } =
+	deriveLocaleConstants(i18nConfig);
+export const HTML_LANG = localeMap(i18nConfig, (def) => def.htmlLang);
+export const OG_LOCALE = localeMap(i18nConfig, (def) => def.ogLocale);
+```
+
+## Translating
+
+Server components / metadata:
+
+```ts
+import { createT } from "@ingram-tech/nk-i18n";
+import { siteScope } from "@/lib/i18n/scopes/site";
+
+const t = createT(locale, siteScope);
+t("Back to directory");
+t('Results for "{query}"', { query });
+t("Showing {from}-{to} of {total, number} codes", { from, to, total });
+```
+
+Client components:
+
+```tsx
+"use client";
+import { useT } from "@ingram-tech/nk-i18n/client";
+import fr from "./i18n.fr.json";
+import nl from "./i18n.nl.json";
+
+const t = useT({ fr, nl });
+```
+
+When the source is a concrete scope or `{ fr, nl }`, `t("…")` is **type-checked**
+against the intersection of the catalogs — a missing translation is a compile
+error, not a silent English fallback. For data-driven keys (a runtime `string`),
+widen the source: `useT<Messages>({ fr, nl })`.
+
+### Scopes
+
+```ts
+// lib/i18n/scopes/site.ts
+import { defineI18nScope } from "@ingram-tech/nk-i18n";
+import fr from "../messages/site.fr.json";
+import nl from "../messages/site.nl.json";
+
+export const siteScope = defineI18nScope({ name: "site", messages: { fr, nl } });
+```
+
+## Locale provider & resolution
+
+Wrap the app once with the server-resolved locale:
+
+```tsx
+// app/layout.tsx
+import { LocaleProvider } from "@ingram-tech/nk-i18n/client";
+
+<LocaleProvider value={locale}>{children}</LocaleProvider>;
+```
+
+Read it in client components (pass the site's `Locale` to narrow it):
+
+```ts
+import { useLocale } from "@ingram-tech/nk-i18n/client";
+const locale = useLocale<Locale>();
+```
+
+Resolve the locale on the server however the site routes. `negotiateAcceptLanguage`
+handles the `Accept-Language` step:
+
+```ts
+import { cookies, headers } from "next/headers";
+import { cache } from "react";
+import { negotiateAcceptLanguage } from "@ingram-tech/nk-i18n";
+import { DEFAULT_LOCALE, SUPPORTED_LOCALES, type Locale } from "./locales";
+
+export const resolveLocale = cache(async (): Promise<Locale> => {
+	const cookie = (await cookies()).get("locale")?.value;
+	if (cookie && (SUPPORTED_LOCALES as string[]).includes(cookie)) return cookie as Locale;
+	const negotiated = negotiateAcceptLanguage(
+		(await headers()).get("accept-language"),
+		SUPPORTED_LOCALES,
+	);
+	return (negotiated as Locale) ?? DEFAULT_LOCALE;
+});
+```
+
+## Exports
+
+- `@ingram-tech/nk-i18n` (server-safe, no React): `createT`, `defineI18nScope`,
+  `defineMessages`, `defineI18nConfig`, `deriveLocaleConstants`, `localeMap`,
+  `negotiateAcceptLanguage`, and the `Messages` / `I18nScope` / `Translator` /
+  `TranslationKey` / `I18nConfig` / `LocaleDefinition` types.
+- `@ingram-tech/nk-i18n/client` (`"use client"`): `LocaleProvider`, `useLocale`,
+  `useT`.

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import { type I18nScope, type Messages, type Translator } from "./core";
+/**
+ * Provide the active locale to client components. Wrap the app once (in the root
+ * layout) with the server-resolved locale.
+ */
+export declare function LocaleProvider({ value, children, }: {
+    value: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Read the active locale. Pass the site's `Locale` union as the type argument
+ * to get it back narrowed: `const locale = useLocale<Locale>()`.
+ */
+export declare function useLocale<TLocale extends string = string>(): TLocale;
+/**
+ * Client translator bound to the active locale from {@link LocaleProvider}.
+ * Message sources are usually passed as fresh object literals each render
+ * (`useT({ fr, nl })`), so they are held in a ref and the translator identity
+ * only changes when the locale changes — safe to list in hook deps.
+ */
+export declare function useT<const TSource extends Messages | I18nScope | undefined>(messagesOrScope?: TSource, runtimeMessages?: Messages | I18nScope): Translator<TSource>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,SAAS,EAA+B,MAAM,OAAO,CAAC;AACnF,OAAO,EAAW,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAIjF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAC9B,KAAK,EACL,QAAQ,GACR,EAAE;IACF,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,CAAC;CACpB,+BAEA;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,KAAK,OAAO,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,KAAK,CAAC,OAAO,SAAS,QAAQ,GAAG,SAAS,GAAG,SAAS,EAC1E,eAAe,CAAC,EAAE,OAAO,EACzB,eAAe,CAAC,EAAE,QAAQ,GAAG,SAAS,GACpC,UAAU,CAAC,OAAO,CAAC,CAarB"}

package/dist/client.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useRef } from "react";
+import { createT } from "./core";
+const LocaleContext = createContext("en");
+/**
+ * Provide the active locale to client components. Wrap the app once (in the root
+ * layout) with the server-resolved locale.
+ */
+export function LocaleProvider({ value, children, }) {
+    return _jsx(LocaleContext.Provider, { value: value, children: children });
+}
+/**
+ * Read the active locale. Pass the site's `Locale` union as the type argument
+ * to get it back narrowed: `const locale = useLocale<Locale>()`.
+ */
+export function useLocale() {
+    return useContext(LocaleContext);
+}
+/**
+ * Client translator bound to the active locale from {@link LocaleProvider}.
+ * Message sources are usually passed as fresh object literals each render
+ * (`useT({ fr, nl })`), so they are held in a ref and the translator identity
+ * only changes when the locale changes — safe to list in hook deps.
+ */
+export function useT(messagesOrScope, runtimeMessages) {
+    const locale = useContext(LocaleContext);
+    const sources = useRef({ messagesOrScope, runtimeMessages });
+    sources.current = { messagesOrScope, runtimeMessages };
+    return useMemo(() => createT(locale, sources.current.messagesOrScope, sources.current.runtimeMessages), [locale]);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAE,aAAa,EAAkB,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACnF,OAAO,EAAE,OAAO,EAAkD,MAAM,QAAQ,CAAC;AAEjF,MAAM,aAAa,GAAG,aAAa,CAAS,IAAI,CAAC,CAAC;AAElD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,EAC9B,KAAK,EACL,QAAQ,GAIR;IACA,OAAO,KAAC,aAAa,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAA0B,CAAC;AAClF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS;IACxB,OAAO,UAAU,CAAC,aAAa,CAAY,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CACnB,eAAyB,EACzB,eAAsC;IAEtC,MAAM,MAAM,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,eAAe,EAAE,eAAe,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,OAAO,GAAG,EAAE,eAAe,EAAE,eAAe,EAAE,CAAC;IACvD,OAAO,OAAO,CACb,GAAG,EAAE,CACJ,OAAO,CACN,MAAM,EACN,OAAO,CAAC,OAAO,CAAC,eAAe,EAC/B,OAAO,CAAC,OAAO,CAAC,eAAe,CAC/B,EACF,CAAC,MAAM,CAAC,CACR,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+export type MissingKeysPolicy = "error" | "warn" | "ignore";
+/**
+ * Metadata for one locale. `label` (the display name, usually native) is
+ * required; sites may add their own fields (e.g. `htmlLang`, `ogLocale`) and
+ * read them back type-safely with {@link localeMap}.
+ */
+export type LocaleDefinition = {
+    label: string;
+    missingKeys?: MissingKeysPolicy;
+};
+export type I18nConfig<TLocales extends Record<string, LocaleDefinition> = Record<string, LocaleDefinition>, TBaseLocale extends string = string> = {
+    baseLocale: TBaseLocale;
+    locales: TLocales;
+};
+type AnyI18nConfig = {
+    baseLocale: string;
+    locales: Record<string, LocaleDefinition>;
+};
+/**
+ * Identity helper that captures the locale table as literal types. Declare the
+ * `Locale` union from the result: `type Locale = keyof typeof config.locales`.
+ * Extra per-locale fields beyond `label`/`missingKeys` are preserved.
+ */
+export declare function defineI18nConfig<const TConfig extends AnyI18nConfig>(config: TConfig): TConfig;
+/**
+ * Derive the common runtime constants from a config: the ordered locale list,
+ * the base locale, and the code→label map.
+ */
+export declare function deriveLocaleConstants<const TConfig extends AnyI18nConfig>(config: TConfig): {
+    SUPPORTED_LOCALES: Array<keyof TConfig["locales"] & string>;
+    DEFAULT_LOCALE: TConfig["baseLocale"];
+    LOCALE_NAMES: Record<keyof TConfig["locales"] & string, string>;
+};
+/**
+ * Build a `Record<Locale, T>` from the config — e.g. an `HTML_LANG` or
+ * `OG_LOCALE` map from fields stored on each locale definition:
+ *
+ *   export const HTML_LANG = localeMap(i18nConfig, (def) => def.htmlLang);
+ */
+export declare function localeMap<const TConfig extends AnyI18nConfig, TValue>(config: TConfig, pick: (def: TConfig["locales"][keyof TConfig["locales"] & string], locale: keyof TConfig["locales"] & string) => TValue): Record<keyof TConfig["locales"] & string, TValue>;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,CACrB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,MAAM,CACzD,MAAM,EACN,gBAAgB,CAChB,EACD,WAAW,SAAS,MAAM,GAAG,MAAM,IAChC;IACH,UAAU,EAAE,WAAW,CAAC;IACxB,OAAO,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF,KAAK,aAAa,GAAG;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EACnE,MAAM,EAAE,OAAO,GACb,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EACxE,MAAM,EAAE,OAAO,GACb;IACF,iBAAiB,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,CAAC;IAC5D,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC;CAChE,CAUA;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,OAAO,SAAS,aAAa,EAAE,MAAM,EACpE,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,CACL,GAAG,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,EAC1D,MAAM,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,KACrC,MAAM,GACT,MAAM,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,EAAE,MAAM,CAAC,CAQnD"}

package/dist/config.js

@@ -0,0 +1,31 @@
+/**
+ * Identity helper that captures the locale table as literal types. Declare the
+ * `Locale` union from the result: `type Locale = keyof typeof config.locales`.
+ * Extra per-locale fields beyond `label`/`missingKeys` are preserved.
+ */
+export function defineI18nConfig(config) {
+    return config;
+}
+/**
+ * Derive the common runtime constants from a config: the ordered locale list,
+ * the base locale, and the code→label map.
+ */
+export function deriveLocaleConstants(config) {
+    const entries = Object.entries(config.locales);
+    return {
+        SUPPORTED_LOCALES: entries.map(([locale]) => locale),
+        DEFAULT_LOCALE: config.baseLocale,
+        LOCALE_NAMES: Object.fromEntries(entries.map(([locale, def]) => [locale, def.label])),
+    };
+}
+/**
+ * Build a `Record<Locale, T>` from the config — e.g. an `HTML_LANG` or
+ * `OG_LOCALE` map from fields stored on each locale definition:
+ *
+ *   export const HTML_LANG = localeMap(i18nConfig, (def) => def.htmlLang);
+ */
+export function localeMap(config, pick) {
+    const entries = Object.entries(config.locales);
+    return Object.fromEntries(entries.map(([locale, def]) => [locale, pick(def, locale)]));
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC/B,MAAe;IAEf,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACpC,MAAe;IAOf,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAsC,CAAC;IACpF,OAAO;QACN,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC;QACpD,cAAc,EAAE,MAAM,CAAC,UAAU;QACjC,YAAY,EAAE,MAAM,CAAC,WAAW,CAC/B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CACzB;KAC3B,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACxB,MAAe,EACf,IAGW;IAGX,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAE5C,CAAC;IACF,OAAO,MAAM,CAAC,WAAW,CACxB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CACjC,CAAC;AAC7B,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,55 @@
+type MessageCatalog = Record<string, string>;
+declare const I18N_KEY_BRAND: unique symbol;
+/**
+ * A set of per-locale message catalogs, keyed by locale code. The English
+ * source text is used as the key, so there is no `en` catalog: a missing lookup
+ * falls back to the key itself.
+ */
+export type Messages = Record<string, MessageCatalog>;
+type I18nKey<TValue extends string = string> = TValue & {
+    readonly [I18N_KEY_BRAND]: "I18nKey";
+};
+/** A named bundle of catalogs, produced by {@link defineI18nScope}. */
+export type I18nScope<TMessages extends Messages = Messages> = {
+    readonly name: string;
+    readonly messages: TMessages;
+};
+export type MessageSource<TMessages extends Messages = Messages> = TMessages | I18nScope<TMessages>;
+type SharedMessageKey<TMessages extends Messages> = keyof TMessages[keyof TMessages] & string;
+type KnownMessageKey<TSource extends MessageSource> = TSource extends I18nScope<infer TMessages> ? SharedMessageKey<TMessages> : TSource extends Messages ? SharedMessageKey<TSource> : never;
+type Unbrand<TValue extends string> = TValue extends I18nKey<infer TRaw> ? TRaw : TValue;
+type LiteralString<TValue extends string> = string extends TValue ? never : TValue;
+type SafeLiteralOrKey<TValue extends string> = TValue extends I18nKey<string> ? TValue : LiteralString<TValue>;
+export type TranslationKey<TSource extends MessageSource> = KnownMessageKey<TSource>;
+type AllowedMessageKey<TSource extends MessageSource | undefined, TValue extends string> = TSource extends MessageSource ? Unbrand<TValue> extends KnownMessageKey<TSource> ? TValue : KnownMessageKey<TSource> : SafeLiteralOrKey<TValue>;
+type DeepMessageKeys<TValue> = TValue extends string ? I18nKey<TValue> : TValue extends (...args: never[]) => unknown ? TValue : TValue extends readonly unknown[] ? {
+    readonly [K in keyof TValue]: DeepMessageKeys<TValue[K]>;
+} : TValue extends Record<PropertyKey, unknown> ? {
+    [K in keyof TValue]: DeepMessageKeys<TValue[K]>;
+} : TValue;
+/**
+ * Translate an English source string to the active locale. With a known message
+ * source the key is checked against the catalogs at compile time; without one,
+ * any literal string is allowed. The optional `values` are interpolated with
+ * ICU MessageFormat (`{name}`, `{count, number}`, plurals, …).
+ */
+export type Translator<TSource extends MessageSource | undefined = undefined> = <const TValue extends string>(english: AllowedMessageKey<TSource, TValue>, values?: Record<string, unknown>) => string;
+/**
+ * Brand a tree of English source strings as translation keys so the compiler
+ * can check them. Returns the value unchanged at runtime.
+ */
+export declare function defineMessages<const TValue>(value: TValue): DeepMessageKeys<TValue>;
+/** Group catalogs under a name so they can be passed to {@link createT}/`useT`. */
+export declare function defineI18nScope<const TMessages extends Messages>(scope: {
+    name: string;
+    messages: TMessages;
+}): I18nScope<TMessages>;
+/**
+ * Build a translator bound to `locale`. The English source is the key, so the
+ * base/source locale needs no catalog — a missing lookup returns the key. Pass
+ * a scope or raw `{ fr, nl, … }` catalogs as the source; `runtimeMessages`
+ * overrides them (e.g. request-scoped data).
+ */
+export declare function createT<const TSource extends MessageSource | undefined>(locale: string, messagesOrScope?: TSource, runtimeMessages?: MessageSource): Translator<TSource>;
+export {};
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}

package/dist/core.js

@@ -0,0 +1,51 @@
+import IntlMessageFormat from "intl-messageformat";
+const cache = new Map();
+function format(message, locale, values) {
+    const key = `${locale}:${message}`;
+    let fmt = cache.get(key);
+    if (!fmt) {
+        fmt = new IntlMessageFormat(message, locale);
+        cache.set(key, fmt);
+    }
+    return fmt.format(values);
+}
+function isI18nScope(source) {
+    return (typeof source === "object" &&
+        source !== null &&
+        "name" in source &&
+        typeof source.name === "string" &&
+        "messages" in source);
+}
+function resolveMessages(source) {
+    if (!source)
+        return undefined;
+    return isI18nScope(source) ? source.messages : source;
+}
+/**
+ * Brand a tree of English source strings as translation keys so the compiler
+ * can check them. Returns the value unchanged at runtime.
+ */
+export function defineMessages(value) {
+    return value;
+}
+/** Group catalogs under a name so they can be passed to {@link createT}/`useT`. */
+export function defineI18nScope(scope) {
+    return scope;
+}
+/**
+ * Build a translator bound to `locale`. The English source is the key, so the
+ * base/source locale needs no catalog — a missing lookup returns the key. Pass
+ * a scope or raw `{ fr, nl, … }` catalogs as the source; `runtimeMessages`
+ * overrides them (e.g. request-scoped data).
+ */
+export function createT(locale, messagesOrScope, runtimeMessages) {
+    const resolvedMessages = resolveMessages(runtimeMessages) ?? resolveMessages(messagesOrScope);
+    const translate = (english, values) => {
+        const translated = resolvedMessages?.[locale]?.[english] ?? english;
+        if (!values)
+            return translated;
+        return format(translated, locale, values);
+    };
+    return translate;
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,iBAAiB,MAAM,oBAAoB,CAAC;AA0EnD,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;AAEnD,SAAS,MAAM,CACd,OAAe,EACf,MAAc,EACd,MAA+B;IAE/B,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,OAAO,EAAE,CAAC;IACnC,IAAI,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,GAAG,GAAG,IAAI,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7C,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC,MAAM,CAAW,CAAC;AACrC,CAAC;AAED,SAAS,WAAW,CAAC,MAAqB;IACzC,OAAO,CACN,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,MAAM,IAAI,MAAM;QAChB,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;QAC/B,UAAU,IAAI,MAAM,CACpB,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,MAAsB;IAC9C,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAe,KAAa;IACzD,OAAO,KAAgC,CAAC;AACzC,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAmC,KAGjE;IACA,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CACtB,MAAc,EACd,eAAyB,EACzB,eAA+B;IAE/B,MAAM,gBAAgB,GACrB,eAAe,CAAC,eAAe,CAAC,IAAI,eAAe,CAAC,eAAe,CAAC,CAAC;IAEtE,MAAM,SAAS,GAAG,CAAC,OAAe,EAAE,MAAgC,EAAU,EAAE;QAC/E,MAAM,UAAU,GAAG,gBAAgB,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC;QACpE,IAAI,CAAC,MAAM;YAAE,OAAO,UAAU,CAAC;QAC/B,OAAO,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEF,OAAO,SAAgC,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createT, defineI18nScope, defineMessages, type I18nScope, type Messages, type MessageSource, type TranslationKey, type Translator, } from "./core";
+export { defineI18nConfig, deriveLocaleConstants, type I18nConfig, localeMap, type LocaleDefinition, type MissingKeysPolicy, } from "./config";
+export { negotiateAcceptLanguage } from "./negotiate";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,OAAO,EACP,eAAe,EACf,cAAc,EACd,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,GACf,MAAM,QAAQ,CAAC;AAChB,OAAO,EACN,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,UAAU,EACf,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACtB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// Server-safe entry — no React. Client hooks live at "@ingram-tech/nk-i18n/client".
+export { createT, defineI18nScope, defineMessages, } from "./core";
+export { defineI18nConfig, deriveLocaleConstants, localeMap, } from "./config";
+export { negotiateAcceptLanguage } from "./negotiate";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,OAAO,EACN,OAAO,EACP,eAAe,EACf,cAAc,GAMd,MAAM,QAAQ,CAAC;AAChB,OAAO,EACN,gBAAgB,EAChB,qBAAqB,EAErB,SAAS,GAGT,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/negotiate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pick the best supported locale from an `Accept-Language` header value.
+ * Compares on the primary subtag only (`fr-BE` → `fr`), case-insensitively, and
+ * returns the first supported match in header order, or `undefined` if none
+ * match. Pure — compose it inside a framework-specific locale resolver.
+ */
+export declare function negotiateAcceptLanguage(header: string | null | undefined, supported: readonly string[]): string | undefined;
+//# sourceMappingURL=negotiate.d.ts.map

package/dist/negotiate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../src/negotiate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,SAAS,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,GAAG,SAAS,CAOpB"}

package/dist/negotiate.js

@@ -0,0 +1,17 @@
+/**
+ * Pick the best supported locale from an `Accept-Language` header value.
+ * Compares on the primary subtag only (`fr-BE` → `fr`), case-insensitively, and
+ * returns the first supported match in header order, or `undefined` if none
+ * match. Pure — compose it inside a framework-specific locale resolver.
+ */
+export function negotiateAcceptLanguage(header, supported) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(",")) {
+        const lang = part.split(";")[0]?.trim().split("-")[0]?.toLowerCase();
+        if (lang && supported.includes(lang))
+            return lang;
+    }
+    return undefined;
+}
+//# sourceMappingURL=negotiate.js.map

package/dist/negotiate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiate.js","sourceRoot":"","sources":["../src/negotiate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACtC,MAAiC,EACjC,SAA4B;IAE5B,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;QACrE,IAAI,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACnD,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@ingram-tech/nk-i18n",
+	"version": "0.1.0",
+	"description": "Type-safe, English-as-key i18n for Ingram Next.js sites — ICU translator, scopes, locale config, and Accept-Language negotiation.",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ingram-technologies/nextkit.git",
+		"directory": "packages/nk-i18n"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./client": {
+			"types": "./dist/client.d.ts",
+			"import": "./dist/client.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"type-check": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"intl-messageformat": "^11.2.8"
+	},
+	"devDependencies": {
+		"@ingram-tech/typescript-config": "workspace:*",
+		"@types/react": "^19.0.0",
+		"react": "^19.0.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.6"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0 || ^19.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
+	}
+}