i18next-resources-to-backend

i18next-resources-to-backend adapts a plain function or a static resource object into a spec-compliant i18next backend module, so translations can be lazily loaded via dynamic import() calls instead of being bundled up front. It runs identically in Node.js, in the browser, and under Deno, and is commonly chained after another backend (such as i18next-http-backend via i18next-chained-backend) so that a namespace missing from a remote source falls back to translations bundled directly in the app.

Internally the loader validates every language and namespace value before it reaches the filesystem or an in-memory resource tree, rejecting path-traversal sequences, prototype-pollution keys like __proto__, backslashes, and overlong identifiers. This matters because those values originate from i18next’s language detector — which can pick them up from a query string, cookie, or URL path — and are handed straight to the caller’s dynamic import() template literal.

What You Get

• A ready-made i18next backend module from a one-line function or object — no need to implement the read(language, namespace, callback) contract yourself
• Support for three loader signatures: callback-style, promise-returning async functions, and plain synchronous returns, auto-detected from the function’s arity
• Built-in input validation that rejects ../ traversal, __proto__/constructor/prototype keys, backslashes, and overlong values before they reach your loader or a static resource tree
• Works identically across Node.js, browser bundlers such as webpack and Vite, and Deno
• TypeScript type definitions (index.d.ts/index.d.mts) with generics for custom language/namespace types

Common Use Cases

• Lazy-loading per-locale JSON translation files via import(./locales/${language}/${namespace}.json) so unused languages never end up in the initial bundle
• Chaining with i18next-http-backend through i18next-chained-backend so a namespace missing from the remote server falls back to translations bundled directly in the app
• Serving translations that already live in memory (fetched, generated, or embedded) through the same backend interface used by file- or network-based backends
• Running identical translation-loading code across a webpack app, a Deno script, and a server-rendered Node app without rewriting the backend for each runtime

Under The Hood

Architecture

The entire package is a single factory function in src/index.js that closes over a caller-supplied res (a function or object) and returns an object shaped to i18next’s BackendModule interface (type: 'backend', a no-op init, and a read(language, namespace, callback) method). Before any lookup happens, read runs both identifiers through a shared isSafeIdentifier guard that rejects traversal sequences, backslashes, control characters, and prototype-pollution keys, then dispatches based on the shape of res: a callback-style function (arity 3+), a sync-or-promise-returning function (arity <3, branching on whether the return value has a .then), or a plain nested object indexed directly by res[language][namespace]. There are no classes, no internal state, and no dependency injection — the whole surface is one closure and one guard function, which keeps the failure modes easy to reason about.

Tech Stack

Source is hand-written ES module JavaScript (not compiled from TypeScript) with a hand-authored .d.ts/.d.mts pair providing the public type surface. Rollup (via @rollup/plugin-babel, @rollup/plugin-commonjs, @rollup/plugin-node-resolve, @rollup/plugin-terser) builds CJS, ESM, and UMD bundles; Babel (@babel/preset-env, @babel/plugin-transform-runtime) transpiles for older targets, with @babel/runtime as the package’s only production dependency. i18next and i18next-chained-backend appear only as devDependencies, consistent with this package acting as an i18next plugin rather than depending on it directly at runtime.

Code Quality

Tests run under Mocha with the should assertion library and sinon, covering both the chained-backend integration scenario and a dedicated unsafe-identifiers.spec.js suite that exercises traversal payloads, prototype-pollution keys, backslashes, and overlong strings against the guard function, alongside positive cases (nested namespaces, empty default namespace, non-ASCII language tags). Type contracts are checked separately via tsd against test/types/*.test-d.ts, and a parallel Deno test suite (test/deno/spec.ts) runs the same package under a different runtime. CI (.github/workflows/node.yml, deno.yml) exercises both. ESLint (eslint-config-standard) lints both JS and, via a separate .ts.eslintrc config, the TypeScript declaration/test files. Error handling is explicit and typed: the safety guard raises descriptive Error objects, and sync loader calls are wrapped in try/catch so thrown errors reach the callback instead of crashing.

What Makes It Unique

Comparable backends (i18next-fs-backend, i18next-http-backend) are tied to one resource source — the filesystem or a network endpoint. This package is source-agnostic: it wraps an arbitrary loader function, which is what makes bundler-driven code-splitting via dynamic import() possible, while the same factory also accepts a plain static object, making it equally usable as an in-memory fallback backend inside i18next-chained-backend. Less common for a small utility package of this kind, a recent version added deliberate hardening against path-traversal and prototype-pollution payloads reaching the caller’s loader or an in-memory resource tree — addressing a real reported issue rather than a theoretical concern.