CLI Tool: Manage Translations from Your Terminal
CLI Tool: Manage Translations from Your Terminal
Developers live in the terminal. Build tools, package managers, linters, formatters, test runners — the entire modern development toolchain is CLI-first. Localization should not be an exception. When translation management requires a web browser, it gets treated as an afterthought. It is not part of the workflow; it is a detour from it.
better-i18n ships a fully-featured CLI tool that integrates translation management directly into your development workflow. You can scan your codebase for hardcoded strings that have not been extracted, push new translation keys to your workspace, pull approved translations for deployment, check coverage, run QA checks, and manage your entire localization pipeline without leaving the terminal.
The CLI is the foundation that makes CI/CD integration possible. It is also the fastest way to perform bulk operations that would take hours to do manually through a web interface.
How It Works
Installation
The better-i18n CLI is distributed as an npm package:
npm install -g @better-i18n/cli
Or use it without installing via npx:
npx @better-i18n/cli <command>
After installation, authenticate with your project API token:
bi18n auth --token <your-api-token>
The token is stored in a local config file and used automatically for subsequent commands. Each token is scoped to a specific project — the same access controls that apply to the web interface apply to the CLI.
Scanning for Hardcoded Strings
The most powerful capability of the CLI is the hardcoded string scanner. It performs a static analysis of your codebase and identifies strings that appear to be user-facing but have not been extracted to a translation key.
bi18n scan ./src --framework react
The scanner understands the major JavaScript and TypeScript frameworks. It distinguishes between:
- User-facing strings that should be translated (button labels, error messages, form field labels)
- Technical strings that should not be translated (log messages, API endpoint paths, CSS class names)
- Already-extracted strings that are referenced via a translation key
For each unextracted string it finds, it shows the file path, line number, the string content, and a suggested translation key name based on your existing naming conventions.
Found 12 untranslated strings:
src/components/Checkout.tsx:47
"Complete your order"
Suggested key: checkout.complete.button.label
src/components/Checkout.tsx:83
"Order Total"
Suggested key: checkout.summary.total.label
...
You can then run bi18n scan --fix to automatically replace the hardcoded strings with translation function calls and push the new keys to your better-i18n workspace in one step.
Pushing Translation Keys
To add new translation keys to your workspace manually:
bi18n push --file ./locales/en.json
Or push a specific set of keys:
bi18n push --key "checkout.complete.button.label" --value "Complete your order"
When you push, the CLI creates the new keys in your better-i18n workspace with "pending translation" status. Your team's translators receive notifications (if configured) and can begin translating immediately through the collaboration workflow.
Pulling Approved Translations
To download the latest approved translations for all languages:
bi18n pull --output ./locales
This creates or updates locale files in the specified directory — en.json, de.json, fr.json, and so on — with the current approved translations from your workspace. Only strings with "approved" or "published" status are included in the pull output by default.
You can pull a specific language:
bi18n pull --language de --output ./locales
Or pull translations with a specific status:
bi18n pull --status approved,published --output ./locales
The pull command is designed to run in CI/CD pipelines immediately before a build, ensuring the build always includes the latest approved translations.
Checking Coverage
To get a coverage report for your project:
bi18n status
Output:
Project: my-saas-app Source language: en (247 strings) Language Translated Approved Coverage de 247 231 93.5% fr 247 189 76.5% es 201 156 63.2% ja 247 247 100.0%
You can exit with a non-zero code if any language falls below a threshold — useful for failing a CI build when coverage drops too low:
bi18n status --min-coverage 80 --fail-below-threshold
Running QA Checks
The CLI exposes the same QA engine available in the web interface:
bi18n qa --language de
This runs all configured QA checks against the German translations and returns a report of errors, warnings, and suggestions. Run it for all languages at once:
bi18n qa --all
Output follows a structured format that is easy to parse in CI scripts. You can also output JSON for integration with other tools:
bi18n qa --all --format json > qa-report.json
Use --fail-on-errors to exit with a non-zero code if any QA errors are found, allowing you to block a deployment when translation errors are present.
Syncing with Version Control
The CLI includes a diff command that shows what has changed in your translations since a specific commit or tag:
bi18n diff --since v2.4.0
This is useful for release notes, for notifying translators about changes, and for understanding the scope of translation work required for an upcoming release.
The version control system in better-i18n records all changes, and the CLI diff command queries that history directly.
CI/CD Integration
A typical CI/CD pipeline with better-i18n looks like this:
# GitHub Actions example - name: Check translation coverage run: bi18n status --min-coverage 80 --fail-below-threshold - name: Run translation QA run: bi18n qa --all --fail-on-errors - name: Pull latest translations run: bi18n pull --status approved --output ./locales - name: Build application run: npm run build
This ensures that every build automatically checks coverage, validates quality, and includes the latest approved translations. Translation problems that would previously slip into production are caught at the build step.
Key Benefits
Localization in the Development Workflow
When translation management is a CLI command, it fits naturally into the same workflow as running tests, running a linter, or building the project. Developers do not need to context-switch to a web interface. Translation becomes part of the standard development loop.
Automated Coverage Enforcement
By adding bi18n status --fail-below-threshold to your CI pipeline, you prevent deployments when translation coverage is below your defined minimum. This is the most reliable way to ensure that a new market does not receive an incompletely translated product. No policy document or manual checklist achieves the same consistency.
Fast Bulk Operations
The web interface is designed for human-speed interaction with individual strings. The CLI is designed for machine-speed bulk operations. Pulling 5,000 translation strings for 12 languages takes seconds from the CLI. The same operation through a web interface would take hours.
Scriptable and Composable
CLI commands are scriptable. You can pipe their output to other tools, combine them in shell scripts, invoke them from Makefiles or task runners, and integrate them into any automation system. The --format json flag on most commands makes it easy to consume output in downstream processing.
Complements the MCP Integration
The CLI and the MCP integration serve complementary use cases. The MCP integration is best for interactive, conversational, single-string operations during active development. The CLI is best for batch operations, CI/CD automation, and scripted workflows. Both connect to the same better-i18n workspace and both respect the same access controls.
Use Cases
Pre-release Translation Audit: The day before a major release, run bi18n scan ./src to find any strings added since the last release that have not been extracted. Run bi18n status to check coverage. Run bi18n qa --all to check for errors. All of this takes under a minute.
Automated Translation Pull in Deployment: The deployment pipeline pulls the latest approved translations before building the application, so the deployed version always includes everything that has been approved up to that point.
New Developer Onboarding: When a developer joins the team, they install the CLI, run bi18n auth, and immediately have full access to the translation workspace from their terminal. No web interface training required for common tasks.
Translation Debt Audit: Run bi18n scan ./src --report on a legacy codebase to get a comprehensive list of all hardcoded strings that have never been extracted. Use the output to scope the localization work required to internationalize the application.
Contractor Handoff: Before handing off a translation project to an external contractor, run bi18n pull --status untranslated --format xliff --language fr to generate an XLIFF file with all strings that need French translation. The contractor works in their preferred CAT tool and returns a completed XLIFF, which you import with bi18n import.
How better-i18n Implements the CLI
The CLI is a Node.js application distributed as a standalone binary via npm. Commands map directly to REST API calls to the better-i18n backend, which means the CLI always has access to the same data and operations as the web interface and the MCP server.
The scanner is the most complex component. It uses a language-aware parser (not a naive regex) to traverse your codebase and identify string literals. The parser understands JSX attributes, template literals, and common i18n function call patterns. False positives (technical strings incorrectly flagged as user-facing) are minimized through a configurable ignore list and a set of heuristics trained on common codebase patterns.
Output formatting is pluggable. Most commands support --format table (default, human-readable), --format json (machine-readable), and --format csv. Some commands additionally support --format xliff for interoperability with CAT tools.
All commands support --dry-run to preview what would happen without making any changes. This is particularly useful before running bi18n scan --fix on a large codebase.
Comparison with Alternatives
i18next-scanner: A popular open-source tool for extracting strings from JavaScript codebases. It writes to local files rather than syncing with a centralized platform. It has no awareness of translation status, team collaboration, or QA. better-i18n's scanner provides a superset of this functionality.
Phrase CLI: Phrase provides a CLI for pushing and pulling translation files. It lacks the codebase scanning capability and the integrated QA checks. The better-i18n CLI covers all file sync use cases plus adds scanning and QA.
Manual File Management: Managing JSON locale files manually, committing them to Git, and merging conflicts is the most common approach for small teams. It does not scale, creates merge conflicts when multiple people work on translations simultaneously, and provides no QA. The CLI is designed to replace this workflow entirely.
Custom API Scripts: Teams sometimes write their own scripts using a localization platform's API. These require ongoing maintenance and lack the convenience of a well-documented, tested CLI. better-i18n's CLI is maintained alongside the platform and always supports the latest API features.
Frequently Asked Questions
Which languages and frameworks does the scanner support?
The scanner supports JavaScript, TypeScript, JSX, TSX, Vue, Svelte, and Python. Framework-specific modes (--framework react, --framework vue, --framework next) enable additional heuristics for common patterns in each framework.
Can I use the CLI in a monorepo?
Yes. The CLI supports per-directory configuration files, so different packages in a monorepo can have different project tokens, different output directories, and different scanner configurations. Run bi18n init in each package root to generate a configuration file.
Does the pull command overwrite files or merge them?
By default, the pull command merges — it updates existing keys and adds new ones without removing keys that are in the local file but not in the workspace. Use --overwrite to replace the file entirely with the workspace content.
Can I use the CLI offline? No. All CLI operations require a network connection to the better-i18n API. The scanner can run offline (it only reads local files), but pushing and pulling require connectivity.
Is the CLI open source? The CLI is open source under the MIT license. You can view the source, submit issues, and contribute on GitHub.
Make Translation a First-Class Part of Your Build Pipeline
Localization problems caught in production are expensive. Localization problems caught in CI are cheap. better-i18n's CLI makes it straightforward to enforce coverage requirements, run QA checks, and pull the latest translations automatically — so production deployments are always in the state you expect.
Start your free trial and install the CLI in your first five minutes.