@phrase/i18next-backend

i18nextPhraseBackend - Phrase Strings backend for i18next

Description

This small library implements an example backend for i18next which retrieves the translations from Phrase OTA releases. The distribution should be created for i18next platform.

Usage

A demo project can be found at https://github.com/phrase/ota-web-demo

Basic usage

npm install --save @phrase/i18next-backend

import i18n from "i18next";
import { I18nextPhraseBackend } from "@phrase/i18next-backend";

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribution: 'DISTRIBUTION_ID',
      environment: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0',
    }
  });

Options

The backend accepts several options:

• distribution (required): The ID of your Phrase Strings OTA distribution
• environment (required): The environment token of your Phrase Strings OTA distribution. Different tokens exist for development (i.e. beta) and production environments
• appVersion: You can prevent some OTA releases from being serverd to certain app versions by providing minimum and maximum app version in Phrase Strings
• cacheExpirationTime: See Caching below
• datacenter: Datacenter.EU (default) or Datacenter.US. Selects the Phrase OTA datacenter
• format: By default this library uses the i18next format, if you use i18next v4 (for the new pluralization resolution strategy), set this to i18next_4
• storage: Custom async storage implementation (see React Native below)

React Native

@phrase/i18next-backend works in React Native when you provide an async storage implementation via the storage option. No React Native dependency is bundled. The package accepts any AsyncStorage-compatible storage implementation.

npm install --save @phrase/i18next-backend @react-native-async-storage/async-storage

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { I18nextPhraseBackend } from '@phrase/i18next-backend';

i18n
  .use(I18nextPhraseBackend)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    backend: {
      distribution: 'DISTRIBUTION_ID',
      environment: 'YOUR_ENVIRONMENT_SECRET',
      storage: AsyncStorage,
    },
  });

Any storage that implements getItem, setItem, and clear returning Promises is accepted (e.g. react-native-mmkv with a small adapter).

react-native-web

For codebases that target both React Native and web via react-native-web, no platform-specific wiring is needed — passing AsyncStorage works on both targets since @react-native-async-storage/async-storage ships a web implementation backed by localStorage. Alternatively, omit storage entirely and the package auto-detects localStorage on the web build.

Offline fallback

To serve bundled translations when the OTA fetch fails, chain this backend with a local fallback using i18next-chained-backend.

npm install --save i18next-chained-backend

Web

Use i18next-http-backend as the fallback — no manual imports needed, files are loaded by URL:

npm install --save i18next-http-backend

import i18n from 'i18next';
import ChainedBackend from 'i18next-chained-backend';
import HttpBackend from 'i18next-http-backend';
import { I18nextPhraseBackend } from '@phrase/i18next-backend';

i18n
  .use(ChainedBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      backends: [I18nextPhraseBackend, HttpBackend],
      backendOptions: [
        { distribution: 'DISTRIBUTION_ID', environment: 'YOUR_ENVIRONMENT_SECRET' },
        { loadPath: '/locales/{{lng}}/{{ns}}.json' },
      ],
    },
  });

React Native

Use i18next-resources-to-backend with a dynamic import — Metro bundles all matching files without manual per-language imports:

npm install --save i18next-resources-to-backend

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import ChainedBackend from 'i18next-chained-backend';
import resourcesToBackend from 'i18next-resources-to-backend';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { I18nextPhraseBackend } from '@phrase/i18next-backend';

i18n
  .use(ChainedBackend)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    backend: {
      backends: [
        I18nextPhraseBackend,
        resourcesToBackend((language, namespace) =>
          import(`./locales/${language}/${namespace}.json`)
        ),
      ],
      backendOptions: [
        {
          distribution: 'DISTRIBUTION_ID',
          environment: 'YOUR_ENVIRONMENT_SECRET',
          storage: AsyncStorage,
        },
      ],
    },
  });

Caching

The library is caching translations and won't check for new translations for 5 minutes. This can be configured by setting the cacheExpirationTime option in the backend configuration for testing purposes. It's recommended to use at least 5 minutes in production.

i18n
  .use(I18nextPhraseBackend)
  .init({
    fallbackLng: 'en',
    backend: {
      distribution: 'DISTRIBUTION_ID',
      environment: 'YOUR_ENVIRONMENT_SECRET',
      appVersion: '1.0.0',
      cacheExpirationTime: 60 * 5, // time in seconds
    }
  });

Releasing a new version

After merging dependency bumps or other changes that warrant a new release:

1. Bump the version field in package.json (and run npm install so package-lock.json picks up the new version) in a PR, e.g. "bump version to x.y.z".
2. Once that PR is merged to main, create a GitHub release with a tag matching the new version (e.g. 1.3.4, no v prefix) targeting main.
3. Publishing the release triggers the release.yml workflow, which runs npm run build and npm publish --provenance --access public to push the package to npmjs.org.