@xndrjs/i18n 0.7.0 → 0.8.0

package/src/codegen-config/build-config.ts

@@ -1,34 +1,15 @@
 import type { CodegenConfigInput } from "../codegen/codegen-config-schema.js";
-import { typeNamesForProject } from "./type-names.js";
-
-export type SetupMode = "single" | "multi";
 
 const GENERATED_DIR = "generated";
 const TRANSLATIONS_DIR = "translations";
 
-export function buildCodegenConfig(mode: SetupMode, project: string): CodegenConfigInput {
-  const typeNames = typeNamesForProject(project);
-  const base = {
-    typesOutput: `${GENERATED_DIR}/i18n-types.generated.ts`,
-    dictionaryOutput: `${GENERATED_DIR}/dictionary.generated.ts`,
-    instanceOutput: `${GENERATED_DIR}/instance.generated.ts`,
-    paramsTypeName: typeNames.paramsTypeName,
-    schemaTypeName: typeNames.schemaTypeName,
-    localeTypeName: typeNames.localeTypeName,
-    factoryName: "createI18n",
-  } satisfies CodegenConfigInput;
-
-  if (mode === "single") {
-    return {
-      dictionary: `${TRANSLATIONS_DIR}/translations.json`,
-      ...base,
-    };
-  }
-
+export function buildCodegenConfig(project: string): CodegenConfigInput {
   return {
+    projectName: project,
     namespaces: {
       default: `${TRANSLATIONS_DIR}/default.json`,
     },
-    ...base,
+    delivery: "split-by-locale",
+    codegenPath: GENERATED_DIR,
   };
 }

package/src/codegen-config/codegen-config.test.ts

@@ -13,17 +13,21 @@ describe("codegen-config", () => {
     }
   });
 
-  it("buildCodegenConfig returns a valid single-mode input shape", () => {
-    const config = buildCodegenConfig("single", "MyApp");
-    expect(config.dictionary).toBe("translations/translations.json");
-    expect(config.paramsTypeName).toBe("MyAppParams");
-    expect(config).not.toHaveProperty("namespaces");
+  it("buildCodegenConfig returns a valid multi-namespace input shape", () => {
+    const config = buildCodegenConfig("MyApp");
+    expect(config.namespaces).toEqual({
+      default: "translations/default.json",
+    });
+    expect(config.projectName).toBe("MyApp");
+    expect(config.codegenPath).toBe("generated");
+    expect(config).not.toHaveProperty("dictionary");
+    expect(config).not.toHaveProperty("paramsTypeName");
   });
 
   it("writeCodegenConfig writes formatted JSON", () => {
     tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-codegen-config-"));
     const configPath = join(tempDir, "i18n/i18n.codegen.json");
-    const config: CodegenConfigInput = buildCodegenConfig("multi", "Demo");
+    const config: CodegenConfigInput = buildCodegenConfig("Demo");
 
     writeCodegenConfig(configPath, config);
 

package/src/codegen-config/index.ts

@@ -2,13 +2,21 @@ export type {
   CodegenConfig,
   CodegenConfigInput,
   DeliveryMode,
+  LoaderStrategy,
+  ResolvedCodegenPaths,
 } from "../codegen/codegen-config-schema.js";
 export {
   codegenConfigKeys,
   DELIVERY_MODES,
-  resolveDeliveryOutputDir,
-  resolveDictionaryOutputPath,
+  LOADER_STRATEGIES,
+  GENERATED_BASENAMES,
+  DEFAULT_FACTORY_NAME,
+  DEFAULT_LOCALE_FALLBACK_CONST_NAME,
+  formatCodegenConfigIssues,
+  resolveCodegenPaths,
+  resolveArtifactsPath,
 } from "../codegen/codegen-config-schema.js";
+export { loadConfig, resolveNamespaces } from "../codegen/config.js";
 
 export type { DeliveryArtifactsMap } from "../codegen/delivery-artifacts.js";
 
@@ -17,6 +25,13 @@ export {
   type SupportedImportExtension,
 } from "../codegen/constants.js";
 
-export { buildCodegenConfig, type SetupMode } from "./build-config.js";
+export { buildCodegenConfig } from "./build-config.js";
 export { inferProjectName, typeNamesForProject } from "./type-names.js";
 export { writeCodegenConfig } from "./write-config.js";
+
+export { runCodegen, type RunCodegenInput, type RunCodegenResult } from "../codegen/run-codegen.js";
+export {
+  regenerateNamespaces,
+  type RegenerateNamespacesInput,
+  type RegenerateNamespacesResult,
+} from "../codegen/regenerate-namespaces.js";

package/src/engine.ts

@@ -1,30 +1,13 @@
 import type { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-import type { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
 import type {
-  KeyDictionary,
   LocaleFallbackMap,
   LocaleOfMulti,
-  LocaleOfSingle,
   MultiDictionary,
+  PartialMultiDictionary,
 } from "./types.js";
 import type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
-import type { I18nScopeSingle, I18nScopeSingleForLocale } from "./scope-single.js";
 import type { MultiParams, ParamsForNamespaces, SchemaForNamespaces } from "./scope-types.js";
 
-/** Mutable translation engine for a single-namespace dictionary. */
-export interface I18nEngineSingle<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  RequestLocales extends string = LocaleOfSingle<Schema>,
-> {
-  readonly __i18nEngineMode: "single";
-  getAll(): Schema;
-  toScope(): I18nScopeSingle<Schema, Params, RequestLocales>;
-  toScope<Locale extends RequestLocales>(options: {
-    locale: Locale;
-  }): I18nScopeSingleForLocale<Schema, Params, Locale>;
-}
-
 /** Mutable translation engine for a multi-namespace dictionary. */
 export interface I18nEngineMulti<
   Schema extends MultiDictionary,
@@ -32,7 +15,8 @@ export interface I18nEngineMulti<
   RequestLocales extends string = LocaleOfMulti<Schema>,
 > {
   readonly __i18nEngineMode: "multi";
-  getAll(): Schema;
+  /** Loaded namespaces only — may be empty at cold start. */
+  getAll(): PartialMultiDictionary<Schema, RequestLocales>;
   toScope<NsList extends readonly (keyof Schema & string)[]>(options: {
     namespaces: NsList;
   }): I18nScopeMulti<
@@ -54,14 +38,6 @@ export interface I18nEngineMulti<
   >;
 }
 
-/** Alias for the default single-namespace engine implementation. */
-export type I18nEngineSingleImpl<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  RequestLocales extends string = LocaleOfSingle<Schema>,
-  Fallback extends LocaleFallbackMap | undefined = undefined,
-> = IcuTranslationProviderSingle<Schema, Params, RequestLocales, Fallback>;
-
 /** Alias for the default multi-namespace engine implementation. */
 export type I18nEngineMultiImpl<
   Schema extends MultiDictionary,

package/src/fetch-artifact.ts

@@ -0,0 +1,16 @@
+/**
+ * Identifies a delivery JSON artifact. Codegen passes this to {@link FetchArtifact};
+ * URL / filesystem mapping is an application concern.
+ */
+export type DeliveryResourceId = {
+  locale: string;
+  namespace: string;
+  /** Present for `delivery: "custom"` (partition key is the area). */
+  area?: string;
+};
+
+/**
+ * Loads a translation JSON artifact by resource id.
+ * Must return the parsed JSON value (not a raw Response).
+ */
+export type FetchArtifact = (id: DeliveryResourceId) => Promise<unknown>;

package/src/i18n-handle.ts

@@ -0,0 +1,202 @@
+import { invokeNamespaceLoader, type NamespaceLoader } from "./builder-loaders.js";
+import type { I18nEngineMultiImpl } from "./engine.js";
+import type {
+  LocaleFallbackMap,
+  LocaleOfMulti,
+  MultiDictionary,
+  PartialKeyDictionary,
+  PartialMultiDictionary,
+} from "./types.js";
+import type { I18nScopeMultiForLocale } from "./scope-multi.js";
+import type { MultiParams, ParamsForNamespaces, SchemaForNamespaces } from "./scope-types.js";
+
+/** Engine handle accepted by {@link createI18nHandle} (with or without localeFallback). */
+type HandleEngine<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+> = I18nEngineMultiImpl<Schema, Params, RequestLocales, LocaleFallbackMap | undefined>;
+
+/** Non-empty namespace list — required by {@link I18nHandle.load} / {@link I18nHandle.peek}. */
+type NonEmptyNamespaces<NS extends readonly string[]> = NS extends readonly [] ? never : NS;
+
+/** Maps a request locale to the delivery partition key (locale itself, or a custom area). */
+export type PartitionForLocale<RequestLocales extends string> = (locale: RequestLocales) => string;
+
+export type I18nHandleOptions<
+  Schema extends MultiDictionary,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+> = {
+  namespaceLoaders?: {
+    [NS in keyof Schema & string]?: NamespaceLoader<
+      PartialKeyDictionary<Schema[NS], RequestLocales> | Schema[NS]
+    >;
+  };
+  /**
+   * Resolves the loader partition for a locale.
+   * Default: identity (`locale → locale`) for split-by-locale.
+   * Custom delivery: codegen injects `locale → LOCALE_DELIVERY_AREA[locale]`.
+   */
+  partitionForLocale?: PartitionForLocale<RequestLocales>;
+};
+
+export type LoadNamespacesInput<
+  Schema extends MultiDictionary,
+  NsList extends readonly (keyof Schema & string)[],
+  Locale extends string,
+> = {
+  namespaces: NonEmptyNamespaces<NsList>;
+  locale: Locale;
+};
+
+/** Locale-bound scope returned by {@link I18nHandle.load} / {@link I18nHandle.peek}. */
+export type ScopeForLocale<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+  NsList extends readonly (keyof Schema & string)[],
+  Locale extends RequestLocales,
+> = I18nScopeMultiForLocale<
+  SchemaForNamespaces<Schema, NsList>,
+  ParamsForNamespaces<Schema, Params, NsList>,
+  RequestLocales,
+  Locale
+>;
+
+/**
+ * Single runtime handle: pass `namespaces` + `locale`; partition is derived via
+ * {@link I18nHandleOptions.partitionForLocale}.
+ */
+export interface I18nHandle<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+> {
+  load<const NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales>(
+    input: LoadNamespacesInput<Schema, NsList, Locale>
+  ): Promise<ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale>>;
+
+  /**
+   * Sync scope when every requested resource is already marked loaded (e.g. hydrate seed).
+   * Returns `null` when a normal async {@link load} is still required.
+   */
+  peek<const NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales>(
+    input: LoadNamespacesInput<Schema, NsList, Locale>
+  ): ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale> | null;
+
+  /** Dictionary (loaded namespaces) + resources for SSR→CSR hydrate. */
+  serialize(): {
+    dictionary: PartialMultiDictionary<Schema, RequestLocales>;
+    resources: readonly (readonly [string, string])[];
+  };
+}
+
+export class I18nHandleImpl<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+> implements I18nHandle<Schema, Params, RequestLocales> {
+  private readonly partitionForLocale: PartitionForLocale<RequestLocales>;
+
+  constructor(
+    private readonly engine: HandleEngine<Schema, Params, RequestLocales>,
+    private readonly options?: I18nHandleOptions<Schema, RequestLocales>
+  ) {
+    this.partitionForLocale = options?.partitionForLocale ?? ((locale) => locale);
+  }
+
+  async load<
+    const NsList extends readonly (keyof Schema & string)[],
+    Locale extends RequestLocales,
+  >(
+    input: LoadNamespacesInput<Schema, NsList, Locale>
+  ): Promise<ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale>> {
+    await applyHandleLoad(this.engine, this.options, input, this.partitionForLocale);
+    return this.engine.toScope({ namespaces: input.namespaces }).forLocale(input.locale);
+  }
+
+  peek<const NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales>(
+    input: LoadNamespacesInput<Schema, NsList, Locale>
+  ): ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale> | null {
+    if (!areHandleResourcesReady(this.engine, this.options, input, this.partitionForLocale)) {
+      return null;
+    }
+    return this.engine.toScope({ namespaces: input.namespaces }).forLocale(input.locale);
+  }
+
+  serialize() {
+    return this.engine.serialize();
+  }
+}
+
+export function createI18nHandle<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string = LocaleOfMulti<Schema>,
+>(
+  engine: HandleEngine<Schema, Params, RequestLocales>,
+  options?: I18nHandleOptions<Schema, RequestLocales>
+): I18nHandle<Schema, Params, RequestLocales> {
+  return new I18nHandleImpl(engine, options);
+}
+
+function areHandleResourcesReady<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+  NsList extends readonly (keyof Schema & string)[],
+  Locale extends RequestLocales,
+>(
+  engine: HandleEngine<Schema, Params, RequestLocales>,
+  options: I18nHandleOptions<Schema, RequestLocales> | undefined,
+  input: LoadNamespacesInput<Schema, NsList, Locale>,
+  partitionForLocale: PartitionForLocale<RequestLocales>
+): boolean {
+  if (input.namespaces.length === 0) {
+    return false;
+  }
+  const partition = partitionForLocale(input.locale);
+  return input.namespaces.every((namespace) => {
+    const loader = options?.namespaceLoaders?.[namespace];
+    if (loader === undefined) {
+      return true;
+    }
+    return engine.hasBuilderResourceLoaded(namespace, partition);
+  });
+}
+
+async function applyHandleLoad<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  RequestLocales extends string,
+  NsList extends readonly (keyof Schema & string)[],
+  Locale extends RequestLocales,
+>(
+  engine: HandleEngine<Schema, Params, RequestLocales>,
+  options: I18nHandleOptions<Schema, RequestLocales> | undefined,
+  input: LoadNamespacesInput<Schema, NsList, Locale>,
+  partitionForLocale: PartitionForLocale<RequestLocales>
+): Promise<void> {
+  if (input.namespaces.length === 0) {
+    throw new Error("[i18n] load() requires a non-empty namespaces array.");
+  }
+
+  const partition = partitionForLocale(input.locale);
+
+  await Promise.all(
+    input.namespaces.map(async (namespace) => {
+      const loader = options?.namespaceLoaders?.[namespace];
+      if (loader === undefined) {
+        return;
+      }
+
+      if (engine.hasBuilderResourceLoaded(namespace, partition)) {
+        return;
+      }
+
+      const data = await invokeNamespaceLoader(loader, partition, { locale: input.locale });
+      engine.applyLoadMergeNamespace(namespace, data);
+      engine.markBuilderResourceLoaded(namespace, partition);
+    })
+  );
+}

package/src/index.ts

@@ -4,46 +4,32 @@ export type {
   LocalesForDeliveryAreaOrAll,
 } from "./builder-types.js";
 
-export type {
-  I18nEngineMulti,
-  I18nEngineMultiImpl,
-  I18nEngineSingle,
-  I18nEngineSingleImpl,
-} from "./engine.js";
+export type { I18nEngineMulti, I18nEngineMultiImpl } from "./engine.js";
 
 export type {
-  CanonicalLoader,
-  I18nBuilderMulti,
-  I18nBuilderMultiForLocale,
-  I18nBuilderMultiInitial,
-  I18nBuilderMultiOptions,
-  I18nBuilderMultiPartitioned,
-  I18nBuilderMultiReady,
-  I18nBuilderSingle,
-  I18nBuilderSingleForLocale,
-  I18nBuilderSingleOptions,
+  I18nHandle,
+  I18nHandleOptions,
+  LoadNamespacesInput,
   NamespaceLoader,
+  PartitionForLocale,
   PartitionedLoader,
+  ScopeForLocale,
 } from "./builder.js";
-export {
-  createI18nBuilder,
-  createI18nMultiBuilder,
-  createI18nSingleBuilder,
-  invokeNamespaceLoader,
-} from "./builder.js";
+export { createI18nHandle, invokeNamespaceLoader } from "./builder.js";
 
-export { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
+export type { BuilderResourceEntry } from "./builder-load-registry.js";
+export type { I18nCreateInput, I18nSerializedState } from "./serialized-state.js";
+export { normalizeI18nCreateInput } from "./serialized-state.js";
 
 export { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
 
 export type { I18nScopeMulti, I18nScopeMultiForLocale } from "./scope-multi.js";
-export type { I18nScopeSingle, I18nScopeSingleForLocale } from "./scope-single.js";
 
 export type {
   MultiParams,
+  NamespaceBoundTranslateFn,
   ParamsForNamespaces,
   SchemaForNamespaces,
-  SingleParams,
 } from "./scope-types.js";
 
 export type {
@@ -51,8 +37,8 @@ export type {
   KeyDictionary,
   LocaleDictionary,
   LocaleFallbackMap,
+  LocaleOfKeys,
   LocaleOfMulti,
-  LocaleOfSingle,
   MissingTranslationContext,
   MultiDictionary,
   PartialKeyDictionary,
@@ -67,11 +53,6 @@ export {
 } from "./resolve-locale.js";
 export type { ResolvedLocaleTemplate } from "./resolve-locale.js";
 
-export {
-  mergeDictionaryLocalesCore,
-  mergeNamespaceLocalesCore,
-  projectDictionaryForDeliveryAreaCore,
-  projectDictionaryLocalesCore,
-  projectNamespaceForDeliveryAreaCore,
-  projectNamespaceLocalesCore,
-} from "./project-locales.js";
+export { mergeDictionaryLocalesCore, mergeNamespaceLocalesCore } from "./project-locales.js";
+
+export type { FetchArtifact, DeliveryResourceId } from "./fetch-artifact.js";

package/src/project-locales.ts

@@ -3,7 +3,7 @@ import type {
   KeyDictionary,
   LocaleFallbackMap,
   LocaleOfMulti,
-  LocaleOfSingle,
+  LocaleOfKeys,
   MultiDictionary,
   PartialKeyDictionary,
   PartialMultiDictionary,
@@ -167,7 +167,7 @@ export function projectDictionaryLocalesCore<T extends MultiDictionary>(
  */
 export function mergeNamespaceLocalesCore<
   T extends KeyDictionary,
-  Locales extends string = LocaleOfSingle<T>,
+  Locales extends string = LocaleOfKeys<T>,
 >(existing: T, incoming: PartialKeyDictionary<T, Locales>): T {
   const merged = structuredClone(existing);
 

package/src/scope-multi.ts

@@ -22,7 +22,7 @@ export interface I18nScopeMulti<
   ): I18nScopeMultiForLocale<Schema, Params, RequestLocales, Locale>;
 }
 
-/** Multi-namespace scope with a bound locale — `t(namespace, key)` and `set(...)` without a locale argument. */
+/** Multi-namespace scope with a bound locale — `t(namespace, key)` without a locale argument. */
 export interface I18nScopeMultiForLocale<
   Schema extends MultiDictionary,
   Params,
@@ -38,14 +38,6 @@ export interface I18nScopeMultiForLocale<
     key: K,
     ...params: ParamArgs<Params[NS][K]>
   ): string;
-  set<
-    const NS extends keyof Schema & keyof Params & string,
-    const K extends keyof Schema[NS] & keyof Params[NS] & string,
-  >(
-    namespace: NS,
-    key: K,
-    template: string
-  ): void;
   forLocale<Next extends RequestLocales>(
     locale: Next
   ): I18nScopeMultiForLocale<Schema, Params, RequestLocales, Next>;
@@ -105,17 +97,6 @@ export class I18nScopeMultiForLocaleImpl<
     return this.engine.getWithLocale(String(namespace), String(key), this.locale, params);
   };
 
-  set = <
-    const NS extends keyof Schema & keyof Params & string,
-    const K extends keyof Schema[NS] & keyof Params[NS] & string,
-  >(
-    namespace: NS,
-    key: K,
-    template: string
-  ): void => {
-    this.engine.patchKeyMulti(String(namespace), String(key), this.locale, template);
-  };
-
   forLocale = <Next extends RequestLocales>(
     locale: Next
   ): I18nScopeMultiForLocaleImpl<Schema, Params, RequestLocales, Next, Fallback> => {

package/src/scope-types.ts

@@ -1,4 +1,4 @@
-import type { KeyDictionary, MultiDictionary } from "./types.js";
+import type { MultiDictionary } from "./types.js";
 
 /** ICU argument map for a multi-namespace schema. */
 export type MultiParams<Schema extends MultiDictionary> = {
@@ -18,10 +18,18 @@ export type ParamsForNamespaces<
   NsList extends readonly (keyof Schema & string)[],
 > = Pick<Params, NsList[number]>;
 
-/** ICU argument map for a single-namespace schema. */
-export type SingleParams<Schema extends KeyDictionary> = {
-  [K in keyof Schema]: unknown;
-};
-
 /** Rest args for `t()` — `never` params omit the third argument. */
 export type ParamArgs<P> = [P] extends [never] ? [] : [params: P];
+
+/**
+ * Namespace-bound `t(key, …)` — locale already bound.
+ * Call sites omit the namespace argument.
+ */
+export type NamespaceBoundTranslateFn<
+  Schema extends MultiDictionary,
+  Params extends MultiParams<Schema>,
+  NS extends keyof Schema & keyof Params & string,
+> = <const K extends keyof Schema[NS] & keyof Params[NS] & string>(
+  key: K,
+  ...params: ParamArgs<Params[NS][K]>
+) => string;