Keyglot for React apps.

What you get

The Keyglot CLI scans your React components for hardcoded user-facing text, extracts it into translation resources, and keeps the result in sync with the Keyglot cloud. keyglot check turns the same data into a localization health report you can run in CI.

The react-i18next adapter understands useTranslation bindings, aliased destructuring, nested component shadowing, the ns:key prefix, and option overrides — so existing apps work without refactoring first.

1. Install and initialize

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

init inspects package.json, picks the react-i18next adapter, and writes keyglot.config.jsonc plus a starter resource file at src/locales/en/common.json. Use --source-locale if your source language is not English:

npx keyglot init --source-locale de

The generated configuration:

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

Point include at your source tree and resourcePattern at wherever your translation files live. Patterns are relative to the directory that contains the configuration, and every workspace command finds that configuration automatically from any nested directory, so monorepos work out of the box.

2. Find and extract hardcoded text

Preview what the scanner found:

npx keyglot scan

HIGH   src/App.tsx:153  "Save changes"  → common:app.save_changes

Every command is a dry run unless you pass --write. Extract the high-confidence findings:

npx keyglot extract --all-high-confidence --write

The transform imports useTranslation, wires the namespace, and replaces the literal with a t() call, preserving interpolations:

// before
<button>Save changes</button>

// after
const { t } = useTranslation('common');
<button>{t('app.save_changes')}</button>

// before
<p>Hello {user.name}</p>

// after
<p>{t('greeting.hello', { name: user.name })}</p>

Individual candidates can be applied selectively with --candidate ID.

3. Connect to the Keyglot cloud

Create a project in Keyglot, then link the workspace:

npx keyglot link --project PROJECT_ID

Set a project API token for the sync commands (Project settings → API tokens):

export KEYGLOT_API_TOKEN=kg_api_...

Then pull the current working copy, push local edits, or both:

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

push never archives cloud-only keys, so nothing disappears by accident.

4. Publish

When the working copy looks right, cut a development publication and promote it to production:

npx keyglot publish --promote

Publications are immutable and atomic; --wait blocks until the build is ready. Use npx keyglot status to inspect the active publications at any time.

5. Run the health check in CI

npx keyglot check

The report covers hardcoded text, missing keys, unused keys, missing translations, placeholder mismatches, plural inconsistencies, and drift between your local resources and the active production publication.

For GitHub Actions, emit workflow annotations and fail only on the categories you care about:

npx keyglot check --format github --fail-on missing-keys,missing-translations,drift

Budgets keep legacy debt from blocking every build:

npx keyglot check --max hardcoded=20 --max unused-keys=200

The same settings live in the check section of keyglot.config.jsonc:

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

By default every category except unused-keys fails the build; --fail-on none, --fail-on all, and per-category budgets are available as flags.

Key conventions

• Namespaces come from useTranslation('ns'), the ns:key prefix, or the { ns } option; unnamespaced calls use the configured default namespace.
• Interpolations use {{name}} placeholders. check compares placeholder sets across locales and fails when they differ.
• Plurals use the _zero, _one, _two, _few, _many, _other suffixes on a shared base key. Every plural family needs _other as the fallback; check verifies this per locale.
• Key style is nested or flat (a.b.c as a single key), configured in the sink and overridable with --key-style on pull, push, and diff.