Keyglot for i18next projects.

Works with the i18next you already have

If your app calls i18next.t() directly — Vue, Svelte, Node, plain DOM scripts, or any setup where useTranslation is not in play — the i18next adapter fits. The CLI scans your source, finds hardcoded strings, extracts them into resources your existing i18next instance can load, and syncs everything with the Keyglot cloud.

1. Initialize

npm install --save-dev https://keyglot.com/downloads/keyglot-cli-0.1.3.tgz
npx keyglot init --adapter i18next

This writes keyglot.config.jsonc and a starter resource at src/locales/en/common.json. Adjust include and resourcePattern to match your project:

{
  "$schema": "https://keyglot.com/schemas/extractor-v2.json",
  "schemaVersion": 2,
  "sourceLocale": "en",
  "include": ["src/**/*.{js,ts}"],
  "adapter": { "kind": "i18next", "defaultNamespace": "common" },
  "sink": {
    "kind": "local",
    "resourcePattern": "src/locales/{locale}/{namespace}.json",
    "keyStyle": "nested"
  }
}

2. Extract hardcoded text

npx keyglot scan                       # preview findings
npx keyglot extract --all-high-confidence --write

For the i18next adapter, the transform emits instance calls with an explicit namespace:

// before
document.title = 'Sign in';

// after
import i18next from 'i18next';
document.title = i18next.t('auth.sign_in', { ns: 'common' });

Interpolations are preserved:

// before
alert(`Welcome back, ${user.name}`);

// after
alert(i18next.t('greeting.welcome_back', { ns: 'common', name: user.name }));

Nothing is written without --write, and --candidate ID applies single findings.

3. Load the resources

Wire the generated files into your i18next initialization exactly as you already do:

import i18next from 'i18next';

await i18next.init({
  lng: 'en',
  fallbackLng: 'en',
  defaultNS: 'common',
  resources: {
    en: { common: en },
    de: { common: de },
  },
});

keyglot pull writes one file per {locale}/{namespace} pair from the cloud working copy, so the shape never drifts from what the extractor writes.

4. Sync with the Keyglot cloud

npx keyglot link --project PROJECT_ID
export KEYGLOT_API_TOKEN=kg_api_...

npx keyglot pull          # cloud working copy → src/locales
npx keyglot push --write  # local resources → cloud working copy
npx keyglot diff          # show local-versus-cloud drift
npx keyglot publish --promote

push batches changes, threads revision guards so concurrent edits surface as errors instead of silent overwrites, and never archives cloud-only keys.

5. Health check and CI

npx keyglot check

The scanner resolves i18next.t('key', { ns: 'ns' }) calls (including default and namespace imports of i18next) to tell you which referenced keys are missing from the source locale, which resource keys are unused, which translations are incomplete, where placeholder sets disagree, where plural families lost their _other fallback, and how far your local files have drifted from the active production publication.

In CI, tighten the failure surface:

npx keyglot check --format github --fail-on missing-keys,missing-translations,drift
npx keyglot check --format sarif          # for GitHub code scanning or other SARIF tooling
npx keyglot check --fail-on none          # report only

Per-category budgets and the default failing categories are configurable in the check section of keyglot.config.jsonc:

{
  "check": {
    "failOn": ["missing-keys", "missing-translations", "placeholders", "plurals", "drift"],
    "maxIssues": { "unused-keys": 200 }
  }
}

Key conventions

• Namespaces resolve from the { ns } call option or the default namespace; the ns:key prefix is honored the same way.
• Interpolations use {{name}} placeholders and are checked for consistency across locales.
• Plurals use _zero, _one, _two, _few, _many, _other suffixes with _other required as the fallback.
• Key style can be nested or flat; pass --key-style to pull, push, and diff to override the configured default.