Dynamic Import

Give locales loaders instead of objects and Intl-T fetches messages when they are needed — the server can preload everything, while the client downloads only the language it is actually showing.

Loaders

import { createTranslation } from "intl-t";

export const t = createTranslation({
  locales: {
    en: () => import("./messages/en.json"),
    es: () => import("./messages/es.json"),
  },
});

import { createTranslation } from "intl-t";

export const t = createTranslation({
  locales: locale => import(`./messages/${locale}.json`) as Promise<typeof import("./messages/en.json")>,
  allowedLocales: ["en", "es"] as const, //  required — keys can't be inferred from a function
});

The await contract

const t = createTranslation({
  locales: { en: () => import("./en.json"), es: () => import("./es.json") },
});

t.es.hello; //  undefined — not loaded yet
await t.es; //  loads only `es`
t.es.hello; //  "¡Hola Mundo!"
await t.es; //  instant — already resolved, never re-fetched

Once loaded, a locale stays cached — awaiting it again is instant and never re-fetches.

Lazy by default

Nothing loads until something is accessed or awaited — in every environment, with either loader form. preload only decides what await t means: the current locale (default) or all of them.

export const { t } = await createTranslation({
  locales: {
    en: () => import("./messages/en.json"),
    es: () => import("./messages/es.json"),
  },
  preload: true, //  `await t` now resolves with every allowed locale loaded
});

Turn it on for servers — one await at boot, then any request renders any language with zero per-request loads. Leave it off for clients — the visitor downloads only the language on screen, and switching fetches the next one on demand. Enabling preload never blocks rendering by itself: the all-locales fetch happens on the first await t, and if you never await, the tree simply stays lazy.

Perfect types: .ts locale files

JSON imports widen strings ("Welcome, {user}!" becomes string), which costs the variable inference. Two ways to keep the full literal types with loaders:

export default {
  homepage: {
    title: "Inicio",
    welcome: "¡Bienvenido, {user}!",
  },
} as const;

import { createTranslation } from "intl-t";
import en from "./messages/en";

//  static: instant first paint, and the source of types

export const t = createTranslation({
  locales: {
    en,
    es: () => import("./messages/es"), //  lazy — typeof import resolves the `as const` statically
  },
  mainLocale: "en",
});

npx @intl-t/declarations ./messages --watch

Failure and retry

A loader that rejects makes the await reject — it does not hang or resolve with missing messages. The failed locale is dropped from the cache, and the next access retries the loader, so a transient network failure heals itself:

await t.en; //  rejects — the import failed
await t.en; //  retries the loader; resolves once it succeeds

Resolving up front

getLocales runs every loader immediately and returns a plain messages record — useful when you want the resolved objects themselves rather than lazy behavior:

import { createTranslation, getLocales } from "intl-t";

const locales = await getLocales(locale => import(`./messages/${locale}.json`), ["en", "es"] as const);

export const { t } = createTranslation({ locales });

Next.js and Suspense

With the Next.js integration, loading is handled for you: await getTranslation() resolves the request locale and its messages, and the provider sends the loaded messages to the client for hydration — the client never re-downloads what the server already rendered.