@webmobix/i18next-plugins

@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