Local and remote JSON sources
Load immutable locale catalogs from memory, HTTP, or Node filesystem paths.
The @puzzle-ui/i18n/sources entry point provides memory and HTTP JSON
catalogs. The Node-only @puzzle-ui/i18n/sources/node entry point provides
filesystem loading.
import { createRemoteCatalogSource } from "@puzzle-ui/i18n/sources";
const source = createRemoteCatalogSource({
url: (locale) => `https://content.example.com/i18n/${locale}.json`,
timeoutMs: 4_000,
retries: 2,
cacheTtlMs: 30_000,
maxResponseBytes: 1_048_576,
});
const englishCatalog = await source.load("en");
source.invalidate("en");The HTTP source validates absolute HTTP(S) URLs, rejects credentials and fragments, disallows redirects, parses and freezes JSON catalogs, isolates caches by locale and namespace, supports abort signals, and exposes explicit invalidation. Request headers are snapshotted when the source is created, and response size is bounded. Errors include the locale and failure category without exposing response credentials or body contents. Configure credentials only in trusted server environments.
TypeScript catalogs
Use createTypeScriptCatalogSource for catalogs imported as application
modules. The source preserves the catalog types and can run a schema validator
once per configured locale:
import { createTypeScriptCatalogSource } from "@puzzle-ui/i18n/sources";
const source = createTypeScriptCatalogSource({
catalogs: { en, fr },
validate(catalog, { locale }) {
catalogSchemas[locale].parse(catalog);
},
});
const englishCatalog = await source.load("en");The validator is application-provided and may use a schema library such as Zod; the package does not add a schema dependency. Catalogs are copied, validated as plain nested objects, and frozen. Locale and namespace lookups are explicit, and abort signals are checked before loading.
For Node filesystem loading, use createFileCatalogSource({ rootDir }) with an
absolute root directory. Complete catalogs use <root>/<locale>.json;
namespaced catalogs use <root>/<locale>/<namespace path>.json. Resolved
symlinks are checked to remain within the configured root. Do not import this
subpath into browser bundles.
These sources return translation catalogs, not CMS documents. For versioned
published/draft content and locale fallback resolution, use the separate
@puzzle-ui/i18n/content adapter contract; a CMS source and schema validator
remain application-provided.