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 i18n-os 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 i18n-os
npx i18n-os 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 i18n-os <command> or the globally installed i18n-os binary.
npx i18n-os <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 i18n-os 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
i18n-os 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