Skip to content
better-i18n.com
Bu sayfada

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.

i18n.config.ts
export const project = "your-org/your-project"; // [!code highlight]
export const defaultLocale = "en"; // [!code highlight]

Workspace Configuration #

For full control over scanning and linting behavior, use the i18nWorkspaceConfig export.

i18n.config.ts
export const project = "your-org/your-project";
export const defaultLocale = "en";

export const i18nWorkspaceConfig = { // [!code highlight]
  project, // [!code highlight]
  defaultLocale, // [!code highlight]
  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.

i18n.config.ts
export const i18nConfig = {
  projectId: "your-org/your-project",
  defaultLocale: "en",
  pull: { // [!code highlight]
    output: "./locales",         // Output directory for JSON files // [!code highlight]
    locales: ["en", "tr", "de"], // Specific locales (default: all) // [!code highlight]
  }, // [!code highlight]
};
OptionTypeDescription
pull.outputstringDirectory for downloaded JSON files. Default: ./locales
pull.localesstring[]Specific locales to download. Default: all from CDN manifest

CLI flags (-o, -l) override these config values.

Lint Options #

OptionTypeDescription
lint.includestring[]Files to scan. Default: ["src", "app", "components", "pages"]
lint.excludestring[]Files to ignore. These are merged with system defaults like node_modules.
lint.rulesobjectCustomize the severity of detection rules.

Rule Severities #

You can set each rule to one of three levels:

  • error: Reports as an error and causes better-i18n scan --ci to fail with exit code 1.
  • warning: Reports as a warning but does not fail the CI (unless --ci is 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)