How do I set up the CLI and scan my project?

6 min readBeginner

The Better i18n CLI is a developer tool that scans your codebase for translation keys and keeps them in sync with the dashboard.

Installation

# With bun (recommended)
bun add -g @better-i18n/cli

# With npm
npm install -g @better-i18n/cli

# With pnpm
pnpm add -g @better-i18n/cli

Verify the installation:

better-i18n --version

Authentication

better-i18n login

This opens a browser window for authentication. Your credentials are stored locally and securely.

Project configuration

Create a config file in your project root:

better-i18n init

This generates better-i18n.config.ts:

import { defineConfig } from '@better-i18n/cli';

export default defineConfig({
  project: 'acme/dashboard',
  sourceLocale: 'en',
  // Directories to scan for translation keys
  include: ['src/**/*.{ts,tsx,js,jsx}'],
  // Directories to exclude
  exclude: ['node_modules', 'dist', '.next'],
});

Scanning your codebase

Run the scanner to find all translation keys:

better-i18n scan

The scanner detects:

t('key') — standard translation function calls
t('namespace:key') — namespaced keys
useTranslations('namespace') — namespace imports
Template literals: t(`key.${dynamic}`) (reports as dynamic key)

Scan output

Scanning src/**/*.{ts,tsx}...

 Found 142 translation keys in 38 files
   • common: 24 keys
   • auth: 18 keys
   • dashboard: 45 keys
   • settings: 32 keys
   • (default): 23 keys

 ⚠ 3 dynamic keys detected (review manually)

Syncing to the dashboard

Push scanned keys to Better i18n:

better-i18n sync

This:

Compares local keys with the dashboard
Creates new keys that don't exist yet
Reports keys that exist in the dashboard but not in code (potential dead keys)

Checking sync status

Verify everything is in sync:

better-i18n check

✓ 142 keys in sync
⚠ 3 keys in code but not in dashboard (run sync to fix)
⚠ 5 keys in dashboard but not in code (potential dead keys)

Running doctor

Diagnose common issues:

better-i18n doctor

This checks your configuration, authentication, API connectivity, and project setup.

CI/CD integration

Add better-i18n check to your CI pipeline to catch missing translations before merge:

# GitHub Actions example
- name: Check translations
  run: better-i18n check --strict

The --strict flag exits with code 1 if any keys are out of sync.

Next steps

Was this article helpful?

How do I set up Better i18n with Next.js?