Configuration
Configure CLI behavior and project context with i18n.config.ts
Better i18n CLI automatically detects your project context from i18n.config.ts. This file is the source of truth for your translation workflow.
Basic Configuration
For simple projects, you only need to export the project slug and default locale.
export const project = "your-org/your-project";
export const defaultLocale = "en"; Workspace Configuration
For full control over scanning and linting behavior, use the i18nWorkspaceConfig export.
export const project = "your-org/your-project";
export const defaultLocale = "en";
export const i18nWorkspaceConfig = {
project,
defaultLocale,
lint: {
// Glob patterns for files to scan
include: ["src/**/*.tsx", "app/**/*.tsx"],
// Files to explicitly ignore (merges with defaults)
exclude: [
"**/skeletons.tsx", // UI skeletons
"**/*.stories.tsx", // Storybook
"**/*.test.tsx", // Tests
"**/components/ui/**", // UI library components (e.g., shadcn)
],
// Rule configuration
rules: {
"jsx-text": "warning", // Show as warning
"jsx-attribute": "warning",
"ternary-locale": "error", // Block CI if detected
},
},
};Pull Options
Configure default behavior for the better-i18n pull command, which downloads translations from CDN to local JSON files.
export const i18nConfig = {
project: "your-org/your-project",
defaultLocale: "en",
pull: {
output: "./locales", // Output directory for JSON files
locales: ["en", "tr", "de"], // Specific locales (default: all)
},
};| Option | Type | Description |
|---|---|---|
pull.output | string | Directory for downloaded JSON files. Default: ./locales |
pull.locales | string[] | Specific locales to download. Default: all from CDN manifest |
CLI flags (-o, -l) override these config values.
Lint Options
| Option | Type | Description |
|---|---|---|
lint.include | string[] | Files to scan. Default: ["src", "app", "components", "pages"] |
lint.exclude | string[] | Files to ignore. These are merged with system defaults like node_modules. |
lint.rules | object | Customize the severity of detection rules. |
Rule Severities
You can set each rule to one of three levels:
error: Reports as an error and causesbetter-i18n scan --cito fail with exit code 1.warning: Reports as a warning but does not fail the CI (unless--ciis combined with specific flags).off: Disables the rule entirely.
Default Exclusions
The CLI automatically ignores these directories to ensure high performance and fewer false positives:
node_modules/**.next/**(Next.js build artifacts)dist/**/build/**(Production bundles).git/**public/**(Static assets)