Fetch Loader

The Fetch Loader is the main way to load translations at runtime. It registers a loader with core; i18n.init() then loads the initial namespaces after all plugins have registered.

Install

npm install @comvi/plugin-fetch-loader

Basic Usage

import { createI18n } from "@comvi/core";
import { FetchLoader } from "@comvi/plugin-fetch-loader";

const i18n = createI18n({
  locale: "en",
  fallbackLocale: "en",
})
  .use(FetchLoader({
    cdnUrl: "https://cdn.comvi.io/your-distribution-id",
  }));

await i18n.init();

Without an API key, translations load from the CDN:

• default namespace: {cdnUrl}/{locale}.json
• other namespaces: {cdnUrl}/{namespace}/{locale}.json

With createI18n({ apiKey }), the loader uses the Comvi API instead. Use this for development or preview flows where you need unpublished translations.

const i18n = createI18n({
  locale: "en",
  fallbackLocale: "en",
  apiKey: import.meta.env.VITE_COMVI_API_KEY,
})
  .use(FetchLoader({
    cdnUrl: import.meta.env.VITE_COMVI_CDN_URL,
    apiBaseUrl: import.meta.env.VITE_COMVI_API_URL,
  }));

Options

interface FetchLoaderOptions {
  cdnUrl: string;
  apiBaseUrl?: string;
  fallback?: FallbackMap;
  onLoadError?: (locale: string, namespace: string, error: Error) => void;
  onLoadSuccess?: (locale: string, namespace: string) => void;
  timeout?: number;
  loadOnInit?: boolean;
  cache?: { revalidate?: number | false; tags?: string[] };
}

cdnUrl

Required. The CDN base URL for your published translations.

FetchLoader({
  cdnUrl: "https://cdn.comvi.io/your-distribution-id",
})

apiBaseUrl

Optional API base URL used when createI18n({ apiKey }) is configured. Defaults to https://api.comvi.io.

fallback

Static imports used when network loading fails. Keys are 'locale' for the default namespace or 'locale:namespace' for explicit namespaces.

FetchLoader({
  cdnUrl: "https://cdn.comvi.io/your-distribution-id",
  fallback: {
    en: () => import("./locales/en.json"),
    de: () => import("./locales/de.json"),
    "en:admin": () => import("./locales/en/admin.json"),
  },
})

timeout

Request timeout in milliseconds. Defaults to 10000.

loadOnInit

Whether to load translations during i18n.init(). Defaults to true. Set to false if you want to defer the first load — for example, when the active locale is determined by a separate detector and you don’t want to fetch the placeholder default. Subsequent locale changes still trigger loads automatically.

cache

Server-side fetch cache options. In Next.js, these are passed to the native fetch() next option:

FetchLoader({
  cdnUrl: "https://cdn.comvi.io/your-distribution-id",
  cache: {
    revalidate: 3600,
    tags: ["comvi-translations"],
  },
})

Notes

• Core controls initial namespace loading during init().
• Later setLocaleAsync() and addActiveNamespace() calls reuse the registered loader.
• Concurrent requests for the same locale/namespace are deduplicated.
• Loader failures are emitted through loadError and can also be observed with onLoadError.