Documentation
Everything you need to automate your i18n workflow.
Getting Started
Installation and project initialization.
5 minCLI Reference
All 8 commands explained with options and examples.
Dashboard Setup
Connect your project to the LocaleForge dashboard via webhook.
Getting Started
Install the CLI globally and run init inside your project. The init command auto-detects your framework and creates a .i18nrc.json config file at the project root.
# Install the CLI
npm install -g @i18n-os/cli
# Navigate to your project
cd your-project
# Initialize LocaleForge
npx localeforge init
What init does
- Detects your framework (Next.js, Create React App, Vite, etc.)
- Identifies your i18n library (next-intl, react-i18next, i18next, react-intl)
- Creates
.i18nrc.jsonwith sensible defaults - Adds recommended scripts to your
package.json
CLI Reference
All commands are available via npx localeforge <command> or the globally installed localeforge binary.
npx localeforge <command> [options]
| Command | Description |
|---|---|
init | Auto-detect framework, create .i18nrc.json config file |
extract | Scan source files for hardcoded strings (dry-run by default) |
migrate | Replace hardcoded strings with t() translation calls |
translate | AI-translate missing keys using configured provider |
validate | Check translation coverage against configured thresholds |
report | Generate coverage report and push to webhook endpoint |
unused | Find translation keys defined but never referenced in source |
split | Split flat locale JSON files into namespace domains |
Common flags
--config <path> Path to .i18nrc.json (default: auto-detect)
--dry-run Preview changes without writing files
--locale <code> Target a specific locale (e.g. fr, de, ja)
--verbose Show detailed output
Webhook Setup
Connect your project to the LocaleForge dashboard by adding a webhook URL to your config. The report command will push coverage data to this endpoint on every run.
Add the following to your .i18nrc.json:
{
"adapter": "next-intl",
"locales": ["en", "fr", "de"],
"defaultLocale": "en",
"webhook": {
"url": "https://app.i18n-os.com/api/ingest/YOUR_PROJECT_ID",
"secret": "whsec_your_webhook_secret"
}
}
Security
The secret value is sent as an X-Webhook-Secret header with every request. Store it in an environment variable and reference it as "secret": "$I18N_WEBHOOK_SECRET" — the CLI will expand it automatically.
Framework Adapters
LocaleForge ships adapters for the four most popular React i18n libraries. The correct adapter is auto-selected by init, or you can set it manually in your config.
next-intl
Full support — server/client import injection, typed messages
react-i18next
useTranslation hook injection, namespace splitting support
i18next
Vanilla i18next config, works with any React setup
FormatJS / react-intl
IntlProvider detection, ICU message format extraction