@adrienlcp/i18n 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrien Lacourpaille
+
+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,83 @@
+# @adrienlcp/i18n
+
+A translation and formatting library for TypeScript, in five files, with **no
+dependencies** and no tie to any framework. Everything it does at runtime it
+does through the platform's `Intl`.
+
+What makes it worth having a package of its own is one property: **the arguments a
+message takes are read off the message itself, at compile time**, with no code
+generation, no extraction step and no build plugin.
+
+```ts
+const EN = defineDictionary({ greeting: 'Hello {name}' })
+
+translate('greeting', { name: 'Ada' }) // fine
+translate('greeting') //             ✗ Expected 2 arguments, but got 1
+translate('greeting', { nom: 'Ada' }) // ✗ 'nom' does not exist in type '{ name: string }'
+translate('greting', { name: 'Ada' }) // ✗ not assignable to '"greeting"'
+```
+
+A second language is typed against the first, down to the placeholders inside
+each message: a missing key, an invented key, a wrong plural table, a `{nom}`
+written where the reference says `{name}` — each is a compile error rather than a
+screen showing a raw placeholder to a user.
+
+## Using it
+
+```bash
+pnpm add @adrienlcp/i18n
+```
+
+```ts
+import { createI18n, defineDictionary } from '@adrienlcp/i18n'
+
+const EN = defineDictionary({ greeting: 'Hello {name}' })
+
+export const i18n = createI18n({
+  defaultLocale: 'en',
+  dictionaries: { en: EN, fr: () => import('./dictionary-fr') }
+})
+
+const translate = await i18n.load('fr')
+translate('greeting', { name: 'Ada' }) // 'Bonjour Ada'
+```
+
+[`documentation.md`](documentation.md) is the documentation — syntax, type
+guarantees, adding a locale, rich text, and the known limitations. Read that
+one.
+
+## Working on it
+
+```bash
+pnpm install                              # at the repository root
+pnpm validate                             # typecheck + biome ci + vitest + build
+pnpm --filter @adrienlcp/i18n test:watch  # this package alone
+```
+
+The suite runs in well under a second: it is pure TypeScript, with no browser and
+no network — the one module a test imports late is a dictionary, so that a lazily
+loaded locale is proved across a real module boundary.
+`src/translator.types.test.ts` is worth knowing about — every rule this library
+enforces is a *compile* error at a call site, and a compile error cannot be
+caught by a test that has to compile, so each one is written there as the type it
+resolves to and checked by `tsc`.
+
+## Where it came from
+
+It started as Web Dev Simplified's
+[`intl-crash-course`](https://github.com/WebDevSimplified/intl-crash-course)
+([video](https://www.youtube.com/watch?v=VbZVx13b2oY)): the `{name:type}`
+placeholder syntax, `defineTranslation` and typed dot-path keys come from there.
+This package adds relative-time and display-name placeholders, cross-locale
+dictionary parity checks, rich text, locale negotiation and lazy loading, and
+drops the React layer and the locale fallback cascade.
+
+It grew apart in two projects, then was reunited in a repository of its own.
+What changed along the way:
+a plural `zero` form that actually fires, one-pass substitution (a repeated
+placeholder used to be filled once, and a substituted value could be read back
+as a placeholder), cross-locale key parity, a plural or enum written without its
+alternatives refusing to compile, a locale registry that binds each language to
+its dictionary once, negotiation that walks both up and down the tag,
+`Intl` formatters built once instead of on every substitution, dictionaries a
+locale can fetch rather than ship, rich text, and tests.

package/dist/create-i18n.d.ts

@@ -0,0 +1,116 @@
+import type { Dictionary, DictionaryFor, MatchingDictionary } from './dictionary.ts';
+import { type Translator } from './translator.ts';
+/**
+ * A dictionary the bundler is told to split out — `() => import('./fr')`. The
+ * module `export default`s it, so TypeScript reads its type at compile time
+ * even though its text arrives at run time: a locale that is fetched late is
+ * held to the reference exactly like one that is imported.
+ */
+export type DictionaryLoader<Reference> = () => Promise<{
+    default: Localized<Reference>;
+}>;
+/**
+ * A dictionary for a second locale, seen from both sides at once: as the tree of
+ * strings the reference demands, and as a dictionary the lookup can walk. It
+ * names `Dictionary` for a second reason — a mapped type over a type parameter
+ * is opaque enough that TypeScript will not rule out its being callable, and a
+ * concrete member is what lets `typeof entry === 'function'` tell a dictionary
+ * from a loader at all.
+ *
+ * The index signature that comes with it switches off TypeScript's own excess
+ * property check, which is why `MatchingDictionary` demands `never` at a key the
+ * reference does not have rather than leaving that to the literal.
+ */
+type Localized<Reference> = Dictionary & DictionaryFor<Reference>;
+type AnyLoader = () => Promise<{
+    default: Dictionary;
+}>;
+/**
+ * One locale's entry held to the reference, whichever way it arrives. A loader
+ * is compared through the dictionary its module `export default`s, so a locale
+ * that is fetched late is checked exactly like one that is imported — and
+ * checked before it is ever called.
+ */
+type Matching<Reference, Entry> = Entry extends () => Promise<{
+    default: infer Loaded;
+}> ? () => Promise<{
+    default: MatchingDictionary<Reference, Loaded>;
+}> : Localized<Reference> & MatchingDictionary<Reference, Entry>;
+export type I18n<Reference, Locale extends string, DefaultLocale extends Locale = Locale> = {
+    /**
+     * A comparator for `Array.sort`, so that a list of names reads the way the
+     * locale orders them — `Émile` between `Adrien` and `Zoé`, where sorting by
+     * code point puts it after both.
+     */
+    compare: (locale: Locale, options?: Intl.CollatorOptions) => (first: string, second: string) => number;
+    /** The locale a preference list falls back to, and the reference dictionary's own. */
+    defaultLocale: DefaultLocale;
+    /**
+     * Fetches what `locale` registered a loader for, and resolves with the
+     * translator that reads it — from then on the one `translator(locale)` hands
+     * out. A locale whose dictionary is already in hand resolves immediately, and
+     * two calls made while one fetch is in flight share it rather than fetching
+     * twice.
+     *
+     * It rejects when the fetch does, and forgets the attempt so that calling it
+     * again retries. Ignoring that rejection is safe: `translator(locale)` goes on
+     * answering with the default locale's translator, which is what the reader
+     * was already seeing.
+     */
+    load: (locale: Locale) => Promise<Translator<Reference>>;
+    /** Every locale the registry knows, whether its dictionary is loaded or not. */
+    locales: readonly Locale[];
+    /** Which of `locales` a list of BCP-47 tags asks for. */
+    negotiate: (preferred: readonly string[]) => Locale;
+    /**
+     * The translator for one locale, synchronously and always: the locale's own
+     * once its dictionary is in hand, the default locale's until then. So a page
+     * renders on the first frame in a language the reader can read, and swaps to
+     * theirs when `load` resolves — no blank screen, no spinner.
+     *
+     * The same function every time it is asked for, and a different one on either
+     * side of a load. That is what a consumer memoises on.
+     */
+    translator: (locale: Locale) => Translator<Reference>;
+};
+/**
+ * Binds every locale to its dictionary once, so that afterwards a locale is all
+ * anyone passes. It is the door callers want: `createTranslator` takes a locale
+ * *and* a dictionary, and nothing there can check that the two go together — a
+ * translator built with the French dictionary and the tag `'en'` reads French
+ * and counts in English.
+ *
+ * The reference dictionary is `defaultLocale`'s, so that is where the keys and
+ * the values are typed from, and every other locale is checked against it.
+ *
+ * A locale registers either its dictionary or a function fetching it, and the
+ * guarantee holds for both — the type of `import('./fr')` is known before it is
+ * ever called. Registering loaders is what keeps a bundler from shipping five
+ * languages to a reader who reads one:
+ *
+ * ```ts
+ * export const i18n = createI18n({
+ *   defaultLocale: 'en',
+ *   dictionaries: {
+ *     en: EN_DICTIONARY,
+ *     fr: () => import('./dictionary-fr'),
+ *     de: () => import('./dictionary-de')
+ *   }
+ * })
+ * ```
+ *
+ * The default locale's entry is a dictionary and never a loader, which the type
+ * forces twice over: it is the reference every key and value is read from, so a
+ * late arrival would leave TypeScript knowing nothing at the moment
+ * `translate('…')` is written — and it is what a reader sees during the moment
+ * their own language is in flight.
+ *
+ * A registry built without a single loader behaves exactly as one built before
+ * they existed: everything is in hand, `translator` never falls back, and
+ * `load` resolves on the spot.
+ */
+export declare const createI18n: <const Entries extends Record<string, Dictionary | AnyLoader>, const DefaultLocale extends keyof Entries & string>({ defaultLocale, dictionaries }: {
+    defaultLocale: DefaultLocale;
+    dictionaries: Entries & { [Locale in keyof Entries]: Matching<Entries[DefaultLocale], Entries[Locale]>; } & Record<DefaultLocale, Localized<Entries[DefaultLocale]>>;
+}) => I18n<Entries[DefaultLocale], keyof Entries & string, DefaultLocale>;
+export {};

package/dist/create-i18n.js

@@ -0,0 +1,132 @@
+import { negotiateLocale } from './negotiate-locale.js';
+import { createTranslator } from './translator.js';
+const isLoader = (registered) => typeof registered === 'function';
+/**
+ * Binds every locale to its dictionary once, so that afterwards a locale is all
+ * anyone passes. It is the door callers want: `createTranslator` takes a locale
+ * *and* a dictionary, and nothing there can check that the two go together — a
+ * translator built with the French dictionary and the tag `'en'` reads French
+ * and counts in English.
+ *
+ * The reference dictionary is `defaultLocale`'s, so that is where the keys and
+ * the values are typed from, and every other locale is checked against it.
+ *
+ * A locale registers either its dictionary or a function fetching it, and the
+ * guarantee holds for both — the type of `import('./fr')` is known before it is
+ * ever called. Registering loaders is what keeps a bundler from shipping five
+ * languages to a reader who reads one:
+ *
+ * ```ts
+ * export const i18n = createI18n({
+ *   defaultLocale: 'en',
+ *   dictionaries: {
+ *     en: EN_DICTIONARY,
+ *     fr: () => import('./dictionary-fr'),
+ *     de: () => import('./dictionary-de')
+ *   }
+ * })
+ * ```
+ *
+ * The default locale's entry is a dictionary and never a loader, which the type
+ * forces twice over: it is the reference every key and value is read from, so a
+ * late arrival would leave TypeScript knowing nothing at the moment
+ * `translate('…')` is written — and it is what a reader sees during the moment
+ * their own language is in flight.
+ *
+ * A registry built without a single loader behaves exactly as one built before
+ * they existed: everything is in hand, `translator` never falls back, and
+ * `load` resolves on the spot.
+ */
+export const createI18n = ({ defaultLocale, dictionaries }) => {
+    const locales = localesOf(dictionaries);
+    const registryWithoutIntersection = new Map(locales.map((locale) => [locale, dictionaries[locale]]));
+    const collators = new Map();
+    const loaded = new Map();
+    const loading = new Map();
+    const translators = new Map();
+    for (const [locale, registered] of registryWithoutIntersection) {
+        if (!isLoader(registered)) {
+            loaded.set(locale, registered);
+        }
+    }
+    const defaultDictionary = dictionaries[defaultLocale];
+    const compare = (locale, options) => {
+        const key = `${locale} ${JSON.stringify(options ?? null)}`;
+        const built = collators.get(key);
+        if (built !== undefined) {
+            return built.compare;
+        }
+        const created = new Intl.Collator(locale, options);
+        collators.set(key, created);
+        return created.compare;
+    };
+    /**
+     * Built once per locale and kept. That is not a speed optimisation: a
+     * consumer memoising on the translator must see a new identity when the
+     * language it reads changes and the same one when it does not, or every
+     * `useMemo` downstream either recomputes forever or serves the old language.
+     */
+    const stableTranslatorFor = (locale, dictionary) => {
+        const built = translators.get(locale);
+        if (built !== undefined) {
+            return built;
+        }
+        const created = createTranslator({ dictionary, locale });
+        translators.set(locale, created);
+        return created;
+    };
+    const translator = (locale) => {
+        const dictionary = loaded.get(locale);
+        return dictionary === undefined
+            ? stableTranslatorFor(defaultLocale, defaultDictionary)
+            : stableTranslatorFor(locale, dictionary);
+    };
+    const load = (locale) => {
+        const dictionary = loaded.get(locale);
+        if (dictionary !== undefined) {
+            return Promise.resolve(stableTranslatorFor(locale, dictionary));
+        }
+        const inFlight = loading.get(locale);
+        if (inFlight !== undefined) {
+            return inFlight;
+        }
+        const loader = registryWithoutIntersection.get(locale);
+        if (!isLoader(loader)) {
+            return Promise.resolve(translator(locale));
+        }
+        const started = fetchDictionary(loader)
+            .then((dictionary) => {
+            loaded.set(locale, dictionary);
+            return stableTranslatorFor(locale, dictionary);
+        })
+            .finally(() => {
+            loading.delete(locale);
+        });
+        loading.set(locale, started);
+        return started;
+    };
+    return {
+        compare,
+        defaultLocale,
+        load,
+        locales,
+        negotiate: (preferred) => negotiateLocale(preferred, {
+            fallback: defaultLocale,
+            supported: locales
+        }),
+        translator
+    };
+};
+/**
+ * Calling the loader through a parameter of its own type, rather than as the
+ * intersection the narrowing leaves behind: an intersection of two call
+ * signatures resolves to the first, and the first is the one the constraint
+ * wrote, which knows only that a dictionary comes back.
+ */
+const fetchDictionary = (loader) => loader().then((module) => module.default);
+/**
+ * `Object.keys` widens to `string[]`, which would make the negotiated locale a
+ * `string` and let any tag reach `translator`. The predicate re-establishes what
+ * the record already knows — its own keys — without a cast.
+ */
+const localesOf = (dictionaries) => Object.keys(dictionaries).filter((key) => key in dictionaries);

package/dist/define-translation.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A placeholder written `{name}` is text and takes a string. One written
+ * `{name:type}` is a value the locale has to format, and the type decides both
+ * what the caller must pass and what this file demands alongside the message.
+ *
+ * `plural` and `enum` carry their alternatives here rather than in the sentence,
+ * because those alternatives are what differs between locales.
+ */
+export type PluralForms = Partial<Record<Exclude<Intl.LDMLPluralRule, 'other'>, string>> & {
+    formatter?: Intl.NumberFormatOptions;
+    other: string;
+    type?: Intl.PluralRuleType;
+};
+/**
+ * `Intl.RelativeTimeFormat` formats a number *of something*, and the message
+ * cannot say which — so the unit is declared here, per placeholder, and the
+ * caller passes the count alone. Negative is the past, positive the future,
+ * which is `Intl`'s own convention.
+ */
+export type RelativeTime = Intl.RelativeTimeFormatOptions & {
+    unit: Intl.RelativeTimeFormatUnit;
+};
+export type TranslationOptions = {
+    date?: Record<string, Intl.DateTimeFormatOptions>;
+    displayname?: Record<string, Intl.DisplayNamesOptions>;
+    enum?: Record<string, Record<string, string>>;
+    list?: Record<string, Intl.ListFormatOptions>;
+    number?: Record<string, Intl.NumberFormatOptions>;
+    plural?: Record<string, PluralForms>;
+    relative?: Record<string, RelativeTime>;
+};
+type OptionsForParam<Type extends string, Name extends string> = Type extends 'date' ? {
+    date?: {
+        [K in Name]?: Intl.DateTimeFormatOptions;
+    };
+} : Type extends 'displayname' ? {
+    displayname: {
+        [K in Name]: Intl.DisplayNamesOptions;
+    };
+} : Type extends 'enum' ? {
+    enum: {
+        [K in Name]: Record<string, string>;
+    };
+} : Type extends 'list' ? {
+    list?: {
+        [K in Name]?: Intl.ListFormatOptions;
+    };
+} : Type extends 'number' ? {
+    number?: {
+        [K in Name]?: Intl.NumberFormatOptions;
+    };
+} : Type extends 'plural' ? {
+    plural: {
+        [K in Name]: PluralForms;
+    };
+} : Type extends 'relative' ? {
+    relative: {
+        [K in Name]: RelativeTime;
+    };
+} : never;
+export type OptionsFor<Message extends string> = Message extends `${string}{${infer Param}}${infer Rest}` ? Param extends `${infer Name}:${infer Type}` ? OptionsForParam<Type, Name> & OptionsFor<Rest> : OptionsFor<Rest> : unknown;
+export type DefinedTranslation = readonly [string, TranslationOptions];
+/**
+ * Pairs a message with what its placeholders need beyond the value itself.
+ * `plural` and `enum` need the alternatives to choose between; `relative` needs
+ * its unit and `displayname` the kind of name to look up. The other three only
+ * configure a formatter, so a message wanting the locale's defaults is written
+ * as a bare string.
+ */
+export declare const defineTranslation: <Message extends string, const Options extends OptionsFor<Message>>(message: Message, options: Options) => readonly [Message, Options];
+export {};

package/dist/define-translation.js

@@ -0,0 +1,8 @@
+/**
+ * Pairs a message with what its placeholders need beyond the value itself.
+ * `plural` and `enum` need the alternatives to choose between; `relative` needs
+ * its unit and `displayname` the kind of name to look up. The other three only
+ * configure a formatter, so a message wanting the locale's defaults is written
+ * as a bare string.
+ */
+export const defineTranslation = (message, options) => [message, options];

package/dist/dictionary.d.ts

@@ -0,0 +1,203 @@
+import type { DefinedTranslation, OptionsFor, PluralForms } from './define-translation.ts';
+/**
+ * A tree of messages for one locale: every leaf is a sentence, every branch a
+ * namespace. A branch is never also a leaf — `host.answerWindow.label`, not
+ * `host.answerWindow` doubling as both.
+ */
+export type Dictionary = {
+    [segment: string]: string | DefinedTranslation | Dictionary;
+};
+/**
+ * A bare string is enough until a placeholder needs alternatives to choose
+ * between — and `{n:plural}` or `{n:enum}` written as one resolves to `never`
+ * here rather than putting the raw key on screen at runtime.
+ *
+ * The last branch has to name `Dictionary` rather than map over anything: a
+ * mapped type over a primitive returns that primitive, so a leaf holding a
+ * number, a `Date` or a function would otherwise pass through unexamined.
+ */
+export type WellFormed<Message> = Message extends string ? Record<string, never> extends OptionsFor<Message> ? Message : never : Message extends DefinedTranslation ? Message : Message extends Dictionary ? {
+    [Segment in keyof Message]: WellFormed<Message[Segment]>;
+} : never;
+/**
+ * The reference dictionary — the one every key and every value is typed from.
+ *
+ * A function rather than a type to `satisfies`, because a type describing a
+ * dictionary has to reach its members through an index signature, and their
+ * type then cannot depend on the message written at each key.
+ */
+export declare const defineDictionary: <const T extends { [Segment in keyof T]: WellFormed<T[Segment]>; }>(dictionary: T) => T;
+/**
+ * What a second locale owes the reference one: the same tree down to the same
+ * leaves, and for a leaf whose placeholders carry alternatives, its own
+ * alternatives in the same shape. The plural categories may differ — French
+ * answers `one` where English answers `other` — so only `other` is required of
+ * either.
+ *
+ * Written as a type to annotate with rather than a function to call, so that
+ * TypeScript's excess property check does the other half of the work: a key the
+ * reference does not have is rejected at the literal, at every depth.
+ *
+ * ```ts
+ * export const FR_DICTIONARY: DictionaryFor<typeof EN_DICTIONARY> = { … }
+ * ```
+ */
+export type DictionaryFor<Reference> = {
+    [Segment in keyof Reference]: Reference[Segment] extends readonly [
+        string,
+        infer Options
+    ] ? readonly [string, LocalizedOptions<Options>] : Reference[Segment] extends string ? string : Reference[Segment] extends Dictionary ? DictionaryFor<Reference[Segment]> : never;
+};
+type LocalizedOptions<Options> = {
+    [K in keyof Options]: K extends 'plural' ? {
+        [Name in keyof Options[K]]: PluralForms;
+    } : K extends 'enum' ? {
+        [Name in keyof Options[K]]: Record<keyof Options[K][Name] & string, string>;
+    } : Options[K];
+};
+/**
+ * What a second locale owes the reference beyond its shape: the same
+ * placeholders, in the same message. `DictionaryFor` types every message as a
+ * bare `string`, so `'Willkommen {nom}'` sits opposite `'Welcome {name}'` and
+ * compiles — the keys are compared across locales, the placeholders inside them
+ * are not. At two languages that is theoretical; at five it is a matter of time.
+ *
+ * The comparison runs both ways, because a locale declaring *fewer*
+ * placeholders than the reference is as wrong as one declaring more, and a
+ * `{count}` written where the reference formats `{count:number}` asks its caller
+ * for a different value. A leaf that disagrees resolves to `never`, which no
+ * message is assignable to, so the error lands on the key that disagrees.
+ *
+ * There is only something to compare while the messages are still literal
+ * types, which is why every dictionary is written through `defineDictionary`.
+ * An annotation widens each message to `string` and takes its placeholders with
+ * it — and so does `satisfies`, whose contextual type is that same `string`.
+ */
+export type MatchingDictionary<Reference, Candidate> = {
+    [Segment in keyof Reference]: MatchingLeaf<Reference[Segment], Segment extends keyof Candidate ? Candidate[Segment] : never>;
+} & KeysTheReferenceLacksRefused<Reference, Candidate>;
+/**
+ * A key the reference does not have, demanded as `never` so that whatever was
+ * written under it is refused. TypeScript's own excess property check cannot do
+ * this here: it fires on a literal with a type of its own, and a dictionary
+ * reaches the registry as a value, from another module as often as not.
+ */
+type KeysTheReferenceLacksRefused<Reference, Candidate> = {
+    [Segment in Exclude<keyof Candidate, keyof Reference>]: never;
+};
+type MatchingLeaf<Reference, Candidate> = Reference extends readonly [
+    string,
+    infer Options
+] ? Matches<Reference, Candidate> extends true ? readonly [string, LocalizedOptions<Options>] : never : Reference extends string ? Matches<Reference, Candidate> extends true ? string : never : Reference extends Dictionary ? MatchingDictionary<Reference, Candidate> : never;
+/**
+ * Everything the message asks of the outside: the values a caller passes, and
+ * the spans a rich rendering marks up. A `<link>` the reference opens and a
+ * locale drops takes the link off the screen as quietly as a renamed
+ * placeholder puts the wrong word on it, so both are compared at once.
+ */
+type Matches<Reference, Candidate> = Same<RichValuesFor<Reference, unknown>, RichValuesFor<Candidate, unknown>>;
+/** Assignable both ways, so that a difference in either is a difference. */
+type Same<Left, Right> = [Left] extends [Right] ? [Right] extends [Left] ? true : false : false;
+type Join<Segment, Rest> = Segment extends string ? Rest extends string ? `${Segment}.${Rest}` : never : never;
+/**
+ * Recursion over a dictionary whose type is still a type parameter has no floor
+ * of its own — TypeScript keeps descending into `T[Segment]` and gives up with
+ * TS2589. A registered dictionary would be concrete and would need none of
+ * this; a generic one has to count the levels down. Past the last one a path
+ * resolves to `never`, so nesting deeper than this fails to compile rather than
+ * losing a key quietly — with a misleading error, since the whole path union
+ * collapses at once.
+ */
+type MaxPathDepth = 10;
+type NextLevel = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+type Level = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
+/** Every leaf, as the dotted path that reaches it. */
+export type DotPath<T, Remaining extends Level = MaxPathDepth> = {
+    [Segment in keyof T]: T[Segment] extends string | DefinedTranslation ? Segment : NextLevel[Remaining] extends Level ? Join<Segment, DotPath<T[Segment], NextLevel[Remaining]>> : never;
+}[keyof T];
+export type LeafAt<T, Path> = Path extends `${infer Segment}.${infer Rest}` ? Segment extends keyof T ? LeafAt<T[Segment], Rest> : never : Path extends keyof T ? T[Path] : never;
+type MessageOf<Translation> = Translation extends readonly [
+    infer Message extends string,
+    unknown
+] ? Message : Translation extends string ? Translation : never;
+type OptionsOf<Translation> = Translation extends readonly [
+    string,
+    infer Options
+] ? Options : unknown;
+type EnumsOf<Options> = Options extends {
+    enum: infer Enums;
+} ? Enums : Record<string, Record<string, string>>;
+type ValueForParam<Type extends string, Name extends string, Enums> = Type extends 'date' ? Date : Type extends 'displayname' ? string : Type extends 'enum' ? Name extends keyof Enums ? keyof Enums[Name] : never : Type extends 'list' ? readonly string[] : Type extends 'number' | 'plural' | 'relative' ? number : never;
+type FormattedCountMarker = '?';
+/**
+ * Every placeholder a message writes, left as written — `name`, `at:date`. What
+ * a caller owes is built from that union in one mapped type rather than folded
+ * together message by message, which is what lets the alternatives a `:plural`
+ * or an `:enum` chooses between be read with the same grammar as the sentence
+ * and land in the same object.
+ *
+ * `{?}` is the plural count's own marker and not a value anyone passes:
+ * `pluralize` fills it from the number it was already handed.
+ */
+type ParamsIn<Message extends string> = Message extends `${string}{${infer Param}}${infer Rest}` ? (Param extends FormattedCountMarker ? never : Param) | ParamsIn<Rest> : never;
+/**
+ * The text a translation carries besides its sentence: every plural form, every
+ * enum member. The runtime substitutes inside whichever one it selects, so a
+ * placeholder written there asks its caller for a value exactly as one in the
+ * sentence does — and the cross-locale comparison holds a locale to it too.
+ *
+ * All of them are read, not the one a count will select: which category answers
+ * is the locale's business, and unknowable from here.
+ */
+type AlternativesIn<Options> = (Options extends {
+    enum: infer Enums;
+} ? TextsIn<Enums> : never) | (Options extends {
+    plural: infer Plurals;
+} ? TextsIn<Plurals> : never);
+/**
+ * Two levels down is every alternative and nothing else: `formatter` is an
+ * object and drops out at `& string`, and `type` is a bare word with no
+ * placeholder in it.
+ */
+type TextsIn<Groups> = {
+    [Name in keyof Groups]: Groups[Name][keyof Groups[Name]];
+}[keyof Groups] & string;
+/**
+ * An untyped `{name}` is text, so it takes a string. A number never arrives
+ * unformatted: it declares `:number` or `:plural` and the locale prints it.
+ *
+ * A message asking for nothing resolves to `unknown`, the neutral element of an
+ * intersection, where `{}` would survive one: `RichValuesFor` intersects this
+ * with a function per span, and a sentence carrying a `<link>` and no
+ * placeholder has to come out as exactly that function.
+ */
+type ValuesForParams<Params extends string, Enums> = [Params] extends [never] ? unknown : {
+    [Param in Params as Param extends `${infer Name}:${string}` ? Name : Param]: Param extends `${infer Name}:${infer Type}` ? ValueForParam<Type, Name, Enums> : string;
+};
+export type ValuesFor<Translation> = ValuesForParams<ParamsIn<MessageOf<Translation>> | ParamsIn<AlternativesIn<OptionsOf<Translation>>>, EnumsOf<OptionsOf<Translation>>>;
+/**
+ * The names a message marks a span with — `Read the <link>terms</link>` names
+ * `link`. Closing tags are skipped rather than collected: they carry the same
+ * name, and a name is wanted once.
+ */
+type TagsIn<Message extends string> = Message extends `${string}<${infer Tag}>${infer Rest}` ? Tag extends `/${string}` ? TagsIn<Rest> : Tag | TagsIn<Rest> : never;
+/**
+ * What a rich rendering asks for: the message's values, plus one function per
+ * marked span. The function decides what a span becomes — a React element, an
+ * HTML string, a terminal escape — which is why nothing here names a framework.
+ */
+export type RichValuesFor<Translation, Node> = ValuesFor<Translation> & {
+    [Tag in TagsIn<MessageOf<Translation>>]: (children: string) => Node;
+};
+/**
+ * A key whose message carries no placeholder, so it renders from nothing but
+ * itself. It is what a lookup table or a piece of state may hold: a key needing
+ * values cannot be translated by whoever ends up reading it back.
+ */
+export type PlainKey<T> = {
+    [Path in DotPath<T>]: keyof ValuesFor<LeafAt<T, Path>> extends never ? Path : never;
+}[DotPath<T>];
+export type ParameterizedKey<T> = {
+    [Path in DotPath<T>]: keyof ValuesFor<LeafAt<T, Path>> extends never ? never : Path;
+}[DotPath<T>];
+export {};

package/dist/dictionary.js

@@ -0,0 +1,8 @@
+/**
+ * The reference dictionary — the one every key and every value is typed from.
+ *
+ * A function rather than a type to `satisfies`, because a type describing a
+ * dictionary has to reach its members through an index signature, and their
+ * type then cannot depend on the message written at each key.
+ */
+export const defineDictionary = (dictionary) => dictionary;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './create-i18n.ts';
+export * from './define-translation.ts';
+export * from './dictionary.ts';
+export * from './negotiate-locale.ts';
+export * from './translator.ts';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './create-i18n.js';
+export * from './define-translation.js';
+export * from './dictionary.js';
+export * from './negotiate-locale.js';
+export * from './translator.js';