@leo-translate/i18next-plugins

i18next backend and post-processor plugins for Leo Translate.

Installation

pnpm add @leo-translate/i18next-plugins

Plugins

LeoBackend

A custom i18next backend that fetches translation JSON files from a remote URL (e.g. Cloudflare R2).

Translation files are resolved using the pattern:

{remoteUrl}/{appId}/{language}/{namespace}.json

Options

| Option | Type | Default | Description | | ----------------------- | --------------------- | --------------------------- | --------------------------------------------------------- | | appId | string \| undefined | undefined | The ID of the application. Required for fetching to work. | | remoteUrl | string | Leo Translate R2 public URL | Base URL for fetching translation files. | | localStorageKeyPrefix | string | 'leo-translate' | Key prefix used by the Chrome extension for overrides. |

LeoPostProcessor

A pass-through i18next post-processor stub. Register it with i18next and opt in per translation call or globally.

Usage

Option 1 — Root import

Import both plugins from the package root:

import { LeoBackend, LeoPostProcessor } from '@leo-translate/i18next-plugins';
import i18n from 'i18next';

i18n
  .use(LeoBackend)
  .use(LeoPostProcessor)
  .init({
    backend: {
      appId: 'my-app',
      remoteUrl: 'https://translations.example.com',
    },
  });

Option 2 — Sub-path imports

Import each plugin individually from its own sub-path:

import { LeoBackend } from '@leo-translate/i18next-plugins/backend';
import { LeoPostProcessor } from '@leo-translate/i18next-plugins/post-processor';
import i18n from 'i18next';

i18n
  .use(LeoBackend)
  .use(LeoPostProcessor)
  .init({
    backend: {
      appId: 'my-app',
      remoteUrl: 'https://translations.example.com',
    },
  });

Sub-path imports are useful when you only need one plugin and want to avoid pulling in the other.

CLI — leo-translate

The package ships a leo-translate binary for managing translation bundles from the command line.

Installation

Install the package globally or as a dev dependency to make the binary available:

# global
pnpm add -g @leo-translate/i18next-plugins

# dev dependency (run via pnpm exec or package.json scripts)
pnpm add -D @leo-translate/i18next-plugins

Commands

leo-translate import <folder>

Discovers all i18next namespace JSON files under a locale folder and uploads them to the Leo Translate backend.

Folder structure expected:

locales/
  en/
    common.json
    dashboard.json
  de/
    common.json
    dashboard.json

Usage:

leo-translate import ./locales --app-id my-app

Options:

| Flag | Type | Default | Description | | ------------- | --------- | ----------------------------------- | --------------------------------------------------------------------------- | | --app-id | string | — | Required. Leo Translate app ID (slug). | | --url | string | https://leo-translate.webmobix.io | Backend URL to upload to. | | --overwrite | boolean | false | Overwrite existing published values. By default, existing keys are skipped. | | --dry-run | boolean | false | Print the full import plan without making any changes. | | --language | string | all languages | Import only the specified language subfolder (e.g. en). |

Examples:

# Preview what would be imported
leo-translate import ./locales --app-id my-app --dry-run

# Import only English, overwriting existing keys
leo-translate import ./locales --app-id my-app --language en --overwrite

# Import to a self-hosted backend
leo-translate import ./locales --app-id my-app --url https://translate.example.com

Authentication:

The first time a live import is run, the CLI opens a browser window to complete an OAuth 2.0 PKCE login flow. After a successful login the token is cached in ~/.leo-translate/credentials.json (mode 0600) and reused on subsequent runs until it expires.

Import results:

After each upload the CLI prints a per-namespace summary of created, updated, and skipped keys. If any errors are returned by the API the CLI exits with code 1.

leo-translate logout

Clears the locally cached authentication token. The next command that requires auth will re-trigger the browser login flow.

leo-translate logout