@transglot/i18next-backend

An i18next Backend plugin that sources catalogs from transglot's OTA/CDN over @transglot/runtime. Register it and i18next loads every namespace from the CDN with the runtime's ETag/304 revalidation and cdnKey auth, so a team already on i18next keeps its <Trans>/t() call-sites and only changes where the JSON comes from.

A naming false-friend of @transglot/react-i18n. THIS package bridges INTO the third-party i18next runtime. @transglot/react-i18n is transglot's OWN React runtime adapter. Pick one, not both.

Install

npm install @transglot/i18next-backend @transglot/runtime i18next

i18next is a peer dependency (you already have it).

Quickstart

import i18next from 'i18next';
import { createTransglotBackend } from '@transglot/i18next-backend';

await i18next
  .use(createTransglotBackend({
    baseUrl: 'https://app.example.com',
    project: 42,
    cdnKey: 'taicdn_…',
  }))
  .init({
    lng: 'en',
    fallbackLng: 'en',
    ns: ['translation'],
    defaultNS: 'translation',
  });

i18next.t('home.title');

You can also register the class and pass options through i18next's own config:

import i18next from 'i18next';
import TransglotI18nextBackend from '@transglot/i18next-backend';

await i18next.use(TransglotI18nextBackend).init({
  lng: 'en',
  ns: ['translation'],
  backend: { baseUrl: 'https://app.example.com', project: 42, cdnKey: 'taicdn_…' },
});

Constructor options and init({ backend }) options are merged; the init values win on a clash.

Namespaces

The CDN route is per-locale (/v1/cdn/{project}/{locale}), so one fetch carries the whole locale. namespaceMode decides how read(lng, ns) slices it:

• single (default): every requested namespace resolves to the WHOLE locale bundle. The fit when your app uses one namespace (i18next's default translation).
• perNamespace: the bundle's TOP-LEVEL keys ARE the namespaces, so read(lng, 'common') returns the common sub-object. The fit when you keep several i18next namespaces in one published bundle and call t('common:save').

createTransglotBackend({ baseUrl, project, cdnKey, namespaceMode: 'perNamespace' });

Options

| Option | Type | Default | Notes | | --- | --- | --- | --- | | baseUrl | string | required | Origin of the transglot app or CDN. | | project | number \| string | required | The CDN URL's {project} segment. | | cdnKey | string | required | The read-only taicdn_… CDN key. | | version | number | latest | Pin to an immutable …/v{n} publish. | | authIn | 'header' \| 'query' | header | X-Transglot-Cdn-Key header or ?key=. | | fetchImpl | typeof fetch | global | Injected fetch (tests / non-browser). | | dev | boolean | false | Runtime console.warn diagnostics. | | namespaceMode | 'single' \| 'perNamespace' | single | See above. |

What the backend returns to i18next

Resources are returned VERBATIM with their nesting preserved, so i18next navigates nested objects with its own keySeparator (default .), runs its own {{var}} interpolation, and resolves plurals from its own key_one/key_other suffix keys. The backend does not flatten keys or rewrite placeholders. Top-level @-prefixed members (Flutter ARB globals like @@locale and per-key metadata like @greeting) are dropped.

Best results come from json_nested (works with i18next's default keySeparator) or json_flat with keySeparator: false. Load failures reach i18next's read callback as typed RuntimeErrors, so i18next's own retry policy applies.

Plurals are i18next's, not ICU

i18next resolves plurals from suffix keys (key_one, key_other, …), NOT from ICU {n, plural, …} strings. If your catalog stores ICU plurals, they render literally through this path. Reach for @transglot/react-intl if you want ICU; its tarball ships an ICU-PARITY.md with the full matrix.