### Install i18next-cli

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Install i18next-cli as a development dependency in your project.

```bash
npm install --save-dev i18next-cli
```

--------------------------------

### Install locize-cli

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Install the locize-cli globally to use the locize integration commands. This is a prerequisite for syncing translations with the Locize platform.

```bash
# Install globally (recommended)
npm install -g locize-cli
```

--------------------------------

### Initialize i18next-cli Configuration

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Create an i18next.config.ts file to configure the CLI. This example sets up locales and extraction paths.

```typescript
import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
});
```

--------------------------------

### Lint Plugin API Example

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Provides a TypeScript example of creating a custom lint plugin for Vue files, demonstrating the use of `lintExtensions`, `lintSetup`, `lintOnLoad`, and `lintOnResult` hooks.

```APIDOC
### Lint Plugin API

```typescript
import type {
  Plugin,
  LinterPlugin,
  LintPluginContext,
  LintIssue,
} from 'i18next-cli';

// You can type your plugin as Plugin (full surface), LinterPlugin (lint-focused),
// or InstrumenterPlugin (instrument-focused)
export const vueLintPlugin = (): LinterPlugin => ({
  name: 'vue-lint-plugin',
  lintExtensions: ['.vue'],
  lintSetup: async (context: LintPluginContext) => {
    context.logger.info('vue lint plugin initialized');
  },
  lintOnLoad: async (code, filePath) => {
    if (!filePath.endsWith('.vue')) return undefined;
    // preprocess SFC/template to lintable JS/TS/JSX text
    return code;
  },
  lintOnResult: async (_filePath, issues: LintIssue[]) => {
    // Example: keep only interpolation issues
    return issues.filter(issue => issue.type === 'interpolation');
  }
});
```
```

--------------------------------

### Extend Recommended Lint Tags and Attributes

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Import and spread recommended lists to extend built-in linting configurations. Ensure 'i18next-cli' is installed.

```typescript
import { defineConfig, recommendedAcceptedTags, recommendedAcceptedAttributes } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
  lint: {
    acceptedTags: ['my-web-component', ...recommendedAcceptedTags],
    acceptedAttributes: ['data-label', ...recommendedAcceptedAttributes]
  }
});
```

--------------------------------

### Example Location Metadata Output

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

This is an example of the JSON output generated by the locationMetadataPlugin, showing translation keys and their usage locations.

```json
{
  "translation": {
    "app.title": [
      "src/App.tsx:12:15",
      "src/components/Header.tsx:8:22"
    ],
    "user.greeting": [
      "src/pages/Profile.tsx:45:10"
    ]
  },
  "common": {
    "button.save": [
      "src/components/SaveButton.tsx:18:7",
      "src/forms/UserForm.tsx:92:5"
    ]
  }
}
```

--------------------------------

### Example YAML Translation File Content

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

This is an example of a YAML translation file generated by i18next-cli, showing a structured key-value representation of translations.

```yaml
app:
  title: My Application
  description: Welcome to our app
button:
  save: Save
  cancel: Cancel
```

--------------------------------

### Generated Merged Namespace File Example

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

When `mergeNamespaces` is enabled, this is an example of the generated output file for a specific language, with namespaces as top-level keys.

```typescript
export default {
  "translation": {
    "key1": "Value 1"
  },
  "common": {
    "keyA": "Value A"
  }
} as const;
```

--------------------------------

### i18next-cli Configuration with Vue Lint Plugin

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Example configuration for i18next-cli using defineConfig. It sets up locales, input/output paths for extraction, and includes a custom Vue lint plugin.

```typescript
import { defineConfig } from 'i18next-cli';
import { vueLintPlugin } from './plugins/vue-lint-plugin.mjs';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{ts,tsx,js,jsx,vue}'],
    output: 'locales/{{language}}/{{namespace}}.json'
  },
  plugins: [
    vueLintPlugin()
  ]
});
```

--------------------------------

### Basic i18next config with defineConfig

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Example of a basic i18next configuration file using TypeScript and the `defineConfig` helper for type safety and IntelliSense. This configuration specifies locales and extraction input/output paths.

```typescript
// i18next.config.ts
import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de', 'fr'],
  extract: {
    input: ['src/**/*.{ts,tsx,js,jsx}'],
    output: 'locales/{{language}}/{{namespace}}.json',
  },
});
```

--------------------------------

### Gulp Integration with i18next-cli

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Example of integrating i18next-cli's runExtractor function into a Gulp build task.

```typescript
import gulp from 'gulp';
import { runExtractor } from 'i18next-cli';

gulp.task('i18next-extract', async () => {
  const config = {
    locales: ['en', 'de', 'fr'],
    extract: {
      input: ['src/**/*.{ts,tsx,js,jsx}'],
      output: 'public/locales/{{language}}/{{namespace}}.json',
    },
  };
  
  await runExtractor(config);
});
```

--------------------------------

### Basic Custom Plugin for i18next-cli

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

A basic custom plugin example for i18next-cli that handles custom file formats. It uses glob to find .vue files and extracts translation keys from specific patterns within them.

```typescript
import { glob } from 'glob';
import { readFile, writeFile } from 'node:fs/promises';

export const myCustomPlugin = () => ({
  name: 'my-custom-plugin',
  
  // Handle custom file formats
  async onEnd(keys) {
    // Extract keys from .vue files
    const vueFiles = await glob('src/**/*.vue');
    for (const file of vueFiles) {
      const content = await readFile(file, 'utf-8');
      const keyMatches = content.matchAll(/\{\{\s*\$t\(['"]([^'"]+)['"]\)/g);
      for (const match of keyMatches) {
        keys.set(`translation:${match[1]}`, {
          key: match[1],
          defaultValue: match[1],
          ns: 'translation'
        });
      }
    }
  }
});
```

--------------------------------

### Locize Cloud Integration

Source: https://context7.com/i18next/i18next-cli/llms.txt

Commands for integrating with the Locize cloud translation management platform. Requires 'locize-cli' to be installed globally. Supports downloading translations, syncing, and migrating Locize configurations.

```bash
npx i18next-cli locize-download
```

```bash
npx i18next-cli locize-sync
```

```bash
npx i18next-cli locize-sync --update-values --dry-run
```

```bash
npx i18next-cli locize-migrate
```

--------------------------------

### Selector API in Strict Mode

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Shows how to use the Selector API in strict mode, where every path must explicitly start with a namespace segment.

```ts
// useTranslation('common');
t($ => $.common.button.save);             // → common.json: button.save

// useTranslation(['auth', 'validation']);
t($ => $.auth.login['Welcome Back!']);    // → auth.json:       login.Welcome Back!
t($ => $.validation.email['Required']);   // → validation.json: email.Required
```

--------------------------------

### Example TypeScript Translation File Content

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

This is an example of a TypeScript translation file generated by i18next-cli, exporting a default object with translation key-value pairs.

```typescript
export default {
  "myKey": "My value"
} as const;
```

--------------------------------

### Create a Custom Vue Plugin for i18next-cli

Source: https://context7.com/i18next/i18next-cli/llms.txt

A custom plugin to handle Vue files, transforming them before parsing and adding custom logic for translation extraction. This example demonstrates `onLoad`, `onVisitNode`, `onEnd`, `afterSync`, `lintOnLoad`, `lintOnResult`, and `instrumentOnResult` hooks.

```typescript
import { defineConfig } from 'i18next-cli';
import type { Plugin, ExtractedKey, ExtractedKeysMap, LintIssue, CandidateString } from 'i18next-cli';
import { readFile } from 'node:fs/promises';
import { glob } from 'glob';

const vuePlugin = (): Plugin => ({
  name: 'vue-plugin',
  // Extension hints used as optimization skip hints
  lintExtensions: ['.vue'],
  instrumentExtensions: ['.vue'],

  // One-time initialization
  setup: async () => {
    console.log('Vue plugin initialized');
  },

  // Transform .vue files to JS/TSX before SWC parses them
  onLoad: async (code, filePath) => {
    if (!filePath.endsWith('.vue')) return undefined; // pass through
    const scriptMatch = code.match(/<script[^>]*>([\s\S]*?)<\/script>/);
    return scriptMatch ? scriptMatch[1] : code;
  },

  // Inject custom scope info for a proprietary hook (e.g. usePageT)
  onVisitNode: (node, context) => {
    if (
      node.type === 'VariableDeclarator' &&
      (node as any).init?.type === 'CallExpression' &&
      (node as any).init?.callee?.value === 'usePageT'
    ) {
      context.setVarInScope('t', { defaultNs: 'pages', keyPrefix: 'dashboard' });
    }
  },

  // Observe every submitted key (read-only snapshot)
  onKeySubmitted: (key: Readonly<ExtractedKey>) => {
    if (key.ns === 'banned') console.warn(`Banned namespace used: ${key.key}`);
  },

  // Post-process the complete key map (add non-JS keys from .vue templates)
  onEnd: async (keys: ExtractedKeysMap) => {
    const vueFiles = await glob('src/**/*.vue');
    for (const file of vueFiles) {
      const content = await readFile(file, 'utf-8');
      for (const [, key] of content.matchAll(/\$t\('([^']+)'\)/g)) {
        keys.set(`translation:${key}`, { key, ns: 'translation', defaultValue: key });
      }
    }
  },

  // Run after translation files are written
  afterSync: async (results, config) => {
    const updatedCount = results.filter(r => r.updated).length;
    console.log(`${updatedCount} translation files updated.`);
  },

  // Lint: preprocess .vue files
  lintOnLoad: async (code, filePath) => {
    if (!filePath.endsWith('.vue')) return undefined;
    const match = code.match(/<template>([\s\S]*)<\/template>/);
    return match ? match[1] : null; // null = skip file
  },

  // Lint: filter issues
  lintOnResult: async (filePath, issues: LintIssue[]) => {
    return issues.filter(i => i.type !== 'interpolation'); // keep only hardcoded
  },

  // Instrument: only process high-confidence candidates
  instrumentOnResult: async (filePath, candidates: CandidateString[]) => {
    return candidates.filter(c => c.confidence >= 0.7);
  },
});

export default defineConfig({
  locales: ['en', 'de'],
  extract: { input: ['src/**/*.{ts,tsx,vue}'], output: 'locales/{{language}}/{{namespace}}.json' },
  plugins: [vuePlugin()],
});
```

--------------------------------

### Locize integration commands

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Commands to manage translations with the Locize platform. Use `locize-download` to get translations, `locize-sync` to upload/sync, and `locize-migrate` to move local translations to Locize.

```bash
# Download translations from Locize
npx i18next-cli locize-download
```

```bash
# Upload/sync translations to Locize  
npx i18next-cli locize-sync
```

```bash
# Migrate local translations to Locize
npx i18next-cli locize-migrate
```

--------------------------------

### Create a Custom Lint Plugin for Vue Files

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Implement a custom linter plugin by extending the `LinterPlugin` interface. This example filters lint issues to only include 'interpolation' types for Vue files.

```typescript
import type {
  Plugin,
  LinterPlugin,
  LintPluginContext,
  LintIssue,
} from 'i18next-cli';

// You can type your plugin as Plugin (full surface), LinterPlugin (lint-focused),
// or InstrumenterPlugin (instrument-focused)
export const vueLintPlugin = (): LinterPlugin => ({
  name: 'vue-lint-plugin',
  lintExtensions: ['.vue'],
  lintSetup: async (context: LintPluginContext) => {
    context.logger.info('vue lint plugin initialized');
  },
  lintOnLoad: async (code, filePath) => {
    if (!filePath.endsWith('.vue')) return undefined;
    // preprocess SFC/template to lintable JS/TS/JSX text
    return code;
  },
  lintOnResult: async (_filePath, issues: LintIssue[]) => {
    // Example: keep only interpolation issues
    return issues.filter(issue => issue.type === 'interpolation');
  }
});
```

--------------------------------

### Initialize i18next-cli Configuration

Source: https://context7.com/i18next/i18next-cli/llms.txt

Use the 'init' command to interactively set up a new i18next-cli configuration file.

```bash
npx i18next-cli init
```

--------------------------------

### Plugin System Overview

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Explains the plugin system for extending i18next-cli capabilities with various hooks for different stages of the CLI process.

```APIDOC
## Plugin System

Create custom plugins to extend the capabilities of `i18next-cli`. The plugin system provides hooks for extraction, linting, and instrumentation, with a single unified `plugins` array.

**Available Hooks:**

- `setup`: Runs once when the CLI is initialized. Use it for any setup tasks.
- `onLoad`: Runs for each file *before* it is parsed. You can use this to transform code (e.g., transpile a custom language to JavaScript).
- `onVisitNode`: Runs for every node in the Abstract Syntax Tree (AST) of a parsed JavaScript/TypeScript file. This provides access to the full parsing context, including variable scope and TypeScript-specific syntax like `satisfies` and `as` operators.
- `onKeySubmitted`: Hook called synchronously for every translation key submitted to the extractor, including duplicates, before the deduplication decision is made.
- `extractKeysFromExpression`: Runs for specific expressions during AST traversal to extract additional translation keys. This is ideal for handling custom syntax patterns or complex key generation logic without managing pluralization manually.
- `extractContextFromExpression`: Runs for specific expressions to extract context values that can't be statically analyzed. Useful for dynamic context patterns or custom context resolution logic.
- `onEnd`: Runs after all JS/TS files have been parsed but *before* the final keys are compared with existing translation files. This is the ideal hook for parsing non-JavaScript files (like `.html`, `.vue`, or `.svelte`) and adding their keys to the collection.
- `afterSync`: Runs after the extractor has compared the found keys with your translation files and generated the final results. This is perfect for post-processing tasks, like generating a report of newly added keys.

**Lint Plugin Hooks:**

- `lintSetup(context)`: Runs once before linting starts. Receives `LintPluginContext` with `config` and `logger`.
- `lintExtensions`: Optional extension hint (for example `['.vue']`). Used as a skip hint/optimization.
- `lintOnLoad(code, filePath)`: Runs before lint parsing for each file.
  - Return `string` to replace source code for linting.
  - Return `undefined` to pass through unchanged.
  - Return `null` to skip linting the file entirely.
- `lintOnResult(filePath, issues)`: Runs after each file is linted. Return a new issues array to filter/augment results, or `undefined` to keep as-is.

**Instrument Plugin Hooks:**

- `instrumentSetup(context)`: Runs once before instrumentation starts. Receives `InstrumentPluginContext` with `config` and `logger`.
- `instrumentExtensions`: Optional extension hint (for example `['.vue']`). Used as a skip hint/optimization.
- `instrumentOnLoad(code, filePath)`: Runs before scanning each file for hardcoded strings.
  - Return `string` to replace source code before scanning.
  - Return `undefined` to pass through unchanged.
  - Return `null` to skip instrumenting the file entirely.
- `instrumentOnResult(filePath, candidates)`: Runs after candidates are detected. Return a new `CandidateString[]` to filter/augment results, or `undefined` to keep as-is.
```

--------------------------------

### Extending Recommended Lint Tags and Attributes

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Demonstrates how to import and spread built-in recommended lists to extend linting configurations for tags and attributes.

```APIDOC
## Extending Recommended Lint Tags and Attributes

You can extend the built-in recommended lists for linting by importing and spreading them in your config:

```typescript
import { defineConfig, recommendedAcceptedTags, recommendedAcceptedAttributes } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
  lint: {
    acceptedTags: ['my-web-component', ...recommendedAcceptedTags],
    acceptedAttributes: ['data-label', ...recommendedAcceptedAttributes]
  }
});
```
```

--------------------------------

### Run i18next-cli Instrument Interactively

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Use the --interactive flag to approve each suggested string transformation during the instrumentation process. This allows for manual review before changes are applied.

```bash
npx i18next-cli instrument --interactive
```

--------------------------------

### getFixedT Function Usage

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Example of using getFixedT to create a translation function with a fixed language and namespace.

```javascript
// getFixedT
const fixedT = getFixedT('en', 'namespace');
fixedT('key');
```

--------------------------------

### Configure i18next-cli with Custom Plugins

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Use the `defineConfig` function to set up i18next-cli, specifying locales, extraction paths, and custom plugins like `myCustomPlugin` and `advancedExtractionPlugin`.

```javascript
import { defineConfig } from 'i18next-cli';
import { myCustomPlugin, advancedExtractionPlugin } from './my-plugins.mjs';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{ts,tsx,vue}'],
    output: 'locales/{{language}}/{{namespace}}.json'
  },
  plugins: [
    myCustomPlugin(),
    advancedExtractionPlugin()
  ]
});
```

--------------------------------

### Trans Component Usage in React

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Examples of using the Trans component for translating strings with interpolation, namespaces, pluralization, and context in React.

```jsx
<Trans i18nKey="welcome">Welcome {{name}}</Trans>
```

```jsx
<Trans ns="common">user.greeting</Trans>
```

```jsx
<Trans count={num}>You have {{num}} message</Trans>
```

```jsx
<Trans context={isMale ? 'male' : 'female'}>A friend</Trans>
```

--------------------------------

### Initialize and Run Linter Programmatically

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Use this programmatic API for full control over linting within your build process. It requires importing the Linter class and defining a configuration object.

```typescript
import { Linter } from 'i18next-cli';
import type { I18nextToolkitConfig } from 'i18next-cli';

const config: I18nextToolkitConfig = {
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{ts,tsx,js,jsx}'],
    output: 'locales/{{language}}/{{namespace}}.json',
  },
};

const linter = new Linter(config);

linter.addEventListener('progress', ({ message }) => console.log(message));

await linter.run();
```

--------------------------------

### runExtractor(config, options?)

Source: https://context7.com/i18next/i18next-cli/llms.txt

The main programmatic entry point for the full extraction pipeline. It validates the configuration, finds all translation keys across source files using SWC AST analysis, writes updated translation files for every configured locale, runs plugin lifecycle hooks, and returns whether any files have changed.

```APIDOC
## runExtractor(config, options?)

### Description
Main programmatic entry point for the full extraction pipeline. Validates config, finds all translation keys across source files via SWC AST analysis, writes updated translation files for every configured locale, runs plugin lifecycle hooks, and returns whether any files changed.

### Usage
```typescript
import { runExtractor, defineConfig } from 'i18next-cli';

const config = defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{ts,tsx}'],
    output: 'locales/{{language}}/{{namespace}}.json',
  },
});

// Standard extraction
const { anyFileUpdated, hasErrors, results } = await runExtractor(config);
console.log('Files updated:', anyFileUpdated);
console.log('Has errors:', hasErrors);
for (const result of results) {
  console.log(`${result.path} (${result.locale}/${result.namespace}):`, result.updated ? 'updated' : 'unchanged');
  // result.newTranslations — the new JSON object written to disk
  // result.existingTranslations — what was on disk before
}

// CI mode: dry-run with sync
const { anyFileUpdated: wouldUpdate } = await runExtractor(config, {
  isDryRun: true,
  syncPrimaryWithDefaults: true, // copy `t('key', 'Default')` values into primary locale file
  syncAll: false,                // also clear synced keys in secondary locales
  trustDerivedDefaults: false,   // also trust key-derived defaults (e.g. t('Hello'))
  quiet: true,                   // suppress spinner output
  logger: {
    info:  (msg) => process.stdout.write(msg + '\n'),
    warn:  (msg) => process.stderr.write(msg + '\n'),
    error: (msg) => process.stderr.write(msg + '\n'),
  },
});
if (wouldUpdate) process.exit(1); // fail CI when translation files are stale
```

### Parameters
#### `config` (object) - Required
Configuration object for the extraction process, typically created using `defineConfig`.

#### `options` (object) - Optional
Options to modify the behavior of `runExtractor`.

- **`isDryRun`** (boolean) - Optional - If true, simulates the extraction without writing files.
- **`syncPrimaryWithDefaults`** (boolean) - Optional - If true, copies `t('key', 'Default')` values into the primary locale file.
- **`syncAll`** (boolean) - Optional - If true, also clears synced keys in secondary locales.
- **`trustDerivedDefaults`** (boolean) - Optional - If true, trusts key-derived defaults (e.g., `t('Hello')`).
- **`quiet`** (boolean) - Optional - If true, suppresses spinner output.
- **`logger`** (object) - Optional - Custom logger object with `info`, `warn`, and `error` methods.

### Returns
An object containing:
- **`anyFileUpdated`** (boolean) - True if any files were updated.
- **`hasErrors`** (boolean) - True if any errors occurred during extraction.
- **`results`** (array) - An array of result objects for each processed locale and namespace.
```

--------------------------------

### Zero-Config Inspection Commands

Source: https://context7.com/i18next/i18next-cli/llms.txt

Perform common i18next-cli tasks like status checks and linting without requiring a configuration file. These commands are useful for quick inspections.

```bash
npx i18next-cli status
```

```bash
npx i18next-cli lint
```

--------------------------------

### Instrument Source Files for t() Calls

Source: https://context7.com/i18next/i18next-cli/llms.txt

Use the 'instrument' command as a first-pass migration tool to automatically wrap hardcoded strings with t() calls. Use --dry-run to preview changes, or --interactive to approve each candidate. Target a specific namespace with --namespace.

```bash
npx i18next-cli instrument --dry-run
```

```bash
npx i18next-cli instrument --interactive
```

```bash
npx i18next-cli instrument --namespace common
```

--------------------------------

### Run i18next-cli Status Check

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Check the translation status of your project. This command provides an overview of localization health.

```bash
npx i18next-cli status
```

--------------------------------

### runSyncer

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Synchronizes translation files based on the provided configuration.

```APIDOC
## runSyncer(config)

### Description
Sync translation files.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (object) - Required - Configuration object for syncing.
```

--------------------------------

### Configure i18next-cli Extraction

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Use `defineConfig` to set up extraction rules, including input/output paths, ignored files, and translation function names. Configure namespace and key separators, and specify patterns for preserving dynamic keys.

```typescript
import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de', 'fr'],
  
  // Key extraction settings
  extract: {
    input: ['src/**/*.{ts,tsx}'],
    output: 'locales/{{language}}/{{namespace}}.json',

    /** Glob pattern(s) for files to ignore during extraction */
    ignore: ['node_modules/**'],

    // Use '.ts' files with `export default` instead of '.json'
    // Or use 'json5' to enable JSON5 features (comments, trailing commas, formatting are tried to be preserved)
    // Or use 'yaml' for YAML format (.yaml or .yml extensions)
    // if the file ending is .json5, .yaml, or .yml it automatically uses the corresponding format
    outputFormat: 'ts',

    // Combine all namespaces into a single file per language (e.g., locales/en.ts)
    // Note: `output` path must not contain `{{namespace}}` when this is true.
    mergeNamespaces: false, 
    
    // Translation functions to detect. Defaults to ['t', '*.t'].
    // Supports wildcards for suffixes.
    functions: ['t', '*.t', 'i18next.t'],
    
    // React components to analyze
    transComponents: ['Trans', 'Translation'],
    
    // HTML tags to preserve in Trans component default values
    transKeepBasicHtmlNodesFor: ['br', 'strong', 'i', 'p'],
    
    // Hook-like functions that return a t function.
    // Supports strings for default behavior or objects for custom argument positions.
    useTranslationNames: [
      'useTranslation', // Standard hook (ns: arg 0, keyPrefix: arg 1)
      'getT',
      'useT',
      {
        name: 'loadPageTranslations',
        nsArg: 1,       // Namespace is the 2nd argument (index 1)
        keyPrefixArg: 2 // Options with keyPrefix is the 3rd (index 2)
      }
    ],
    
    // Namespace and key configuration
    defaultNS: 'translation', // If set to false it will not generate any namespace, useful if i.e. the output is a single language json with 1 namespace (and no nesting).
    fallbackNS: 'fallback', // Namespace to use as fallback when a key is missing in the current namespace for a locale. (default undefined)
    nsSeparator: ':',
    keySeparator: '.', // Or `false` to disable nesting and use flat keys
    contextSeparator: '_',
    pluralSeparator: '_',
    
    // Preserve dynamic keys matching patterns
    preservePatterns: [
      // Key patterns
      'dynamic.feature.*',      // Matches dynamic.feature.anything
      'generated.*.key',        // Matches generated.anything.key
      
      // Namespace patterns
      'assets:*',               // Preserves ALL keys in the 'assets' namespace
      'common:button.*',        // Preserves keys like common:button.save, common:button.cancel
      'errors:api.*',           // Preserves keys like errors:api.timeout, errors:api.server
      
      // Specific key preservation across namespaces
      'dynamic:user.*.profile', // Matches dynamic:user.admin.profile, dynamic:user.guest.profile
    ],
    
    /**
     * When true, preserves all context variants of keys that use context parameters,
     * across every configured locale. For example, if 'friend' is used with a context
     * option in source code, variants like 'friend_male' and 'friend_female' are kept
     * in the primary language even when they're not referenced explicitly, and are
     * propagated to secondary locales with empty placeholders so every language ends
     * up with the same key skeleton.
     * (default: false)
     */
    preserveContextVariants: false,

    // Output formatting
    sort: true, // can be also a sort function => i.e. (a, b) => a.key > b.key ? -1 : a.key < b.key ? 1 : 0, // sort in reverse order
    indentation: 2, // can be also a string
    
    // Primary language settings
    primaryLanguage: 'en', // Defaults to the first locale in the `locales` array
    secondaryLanguages: ['de', 'fr'], // Defaults to all locales except primaryLanguage

    // Default value for missing keys in secondary languages
    // Can be a string, function, or object for flexible fallback strategies
    defaultValue: '', // Simple string: all missing keys get this value
    
    // Or use a function for dynamic defaults:
    // defaultValue: (key, namespace, language, value) => key, // i18next-parser style: use key as value
    // defaultValue: (key, namespace, language, value) => `TODO: translate ${key}`, // Mark untranslated keys
    // defaultValue: (key, namespace, language, value) => language === 'de' ? 'German TODO' : 'TODO', // Language-specific

    /** If true, keys that are not found in the source code will be removed from translation files. (default: true) */
    removeUnusedKeys: true,

    // Namespaces to ignore during extraction, status, and sync operations.
    // Useful for monorepos where shared namespaces are managed elsewhere.
    // Keys using these namespaces will be excluded from processing.
    ignoreNamespaces: ['shared', 'common'], // Optional

  }
});

```

--------------------------------

### Add Custom Plugins

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

A placeholder for adding custom plugins to extend i18next-cli functionality.

```javascript
plugins: [
    // Add custom plugins here
  ]
```

--------------------------------

### Selector API with Multi-Namespace

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Demonstrates the Selector API with a multi-namespace hook. Secondary namespaces are used as prefixes for path routing.

```ts
const { t } = useTranslation(['auth', 'validation']);

t($ => $.login['Welcome Back!']);                // → auth.json:       login.Welcome Back!
t($ => $.validation.email['Required']);          // → validation.json: email.Required
t($ => $.email['Required'], { ns: 'validation'}); // → validation.json: email.Required
```

--------------------------------

### Migrate Configuration from i18next-parser

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Use the `npx i18next-cli migrate-config` command to automatically convert your legacy `i18next-parser.config.js` to the new `i18next.config.ts` format.

```bash
npx i18next-cli migrate-config
```

--------------------------------

### runSyncer(config, options?)

Source: https://context7.com/i18next/i18next-cli/llms.txt

Synchronizes secondary locale translation files against the primary locale. It preserves existing translations, adds missing keys, removes obsolete keys, and handles locale-specific CLDR plural forms.

```APIDOC
## runSyncer(config, options?)

### Description
Synchronizes secondary locale translation files against the primary locale. Preserves existing translations, adds missing keys with a configurable default value, removes keys no longer in the primary, and correctly handles locale-specific CLDR plural forms (e.g., `_many` for French/Spanish).

### Parameters
#### Path Parameters
- **config** (object) - Required - Configuration object for the syncer.
- **options** (object) - Optional - Options for the synchronization process. Example: `{ quiet: false }`.

### Request Example
```typescript
import { runSyncer } from 'i18next-cli';

await runSyncer(config, { quiet: false });
```

### Response Example
```json
// Reads: locales/en/translation.json  (primary)
// {
//   "button.save": "Save",
//   "button.cancel": "Cancel",
//   "greeting_one": "Hello",
//   "greeting_other": "Hellos"
// }

// Writes: locales/de/translation.json (secondary — merged result)
// {
//   "button.save": "",          ← new key, empty placeholder
//   "button.cancel": "Abbrechen",  ← existing, preserved
//   "greeting_one": "",
//   "greeting_other": "",
//   "greeting_many": ""           ← locale-specific CLDR form added for 'de'
// }
```
```

--------------------------------

### Preview Instrument Changes with Dry Run

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Use the `--dry-run` option to preview the transformations that the instrument command would make without actually modifying any files. This is recommended for initial checks.

```bash
npx i18next-cli instrument --dry-run
```

--------------------------------

### Configure i18next-cli with Location Metadata Plugin

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Configure your i18next.config.ts file to use the locationMetadataPlugin. Specify the output path for the metadata file.

```typescript
// i18next.config.ts
import { defineConfig } from 'i18next-cli';
import { locationMetadataPlugin } from './plugins/location-metadata.mjs';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{ts,tsx}'],
    output: 'locales/{{language}}/{{namespace}}.json',
  },
  plugins: [
    locationMetadataPlugin({
      output: 'locales/metadata.json'
    })
  ]
});
```

--------------------------------

### Basic i18next config without defineConfig

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Alternative configuration for i18next using JavaScript, without the `defineConfig` helper. This is suitable if you are not using TypeScript or prefer a plain object configuration. The functionality remains the same.

```javascript
// i18next.config.js
export default {
  locales: ['en', 'de', 'fr'],
  extract: {
    input: ['src/**/*.{ts,tsx,js,jsx}'],
    output: 'locales/{{language}}/{{namespace}}.json',
  },
};
```

--------------------------------

### Configure i18next-cli with Recommended Tags/Attributes

Source: https://context7.com/i18next/i18next-cli/llms.txt

Extend built-in recommended JSX tag and attribute lists for translation linting by using spread syntax in your i18next-cli configuration.

```typescript
import { defineConfig, recommendedAcceptedTags, recommendedAcceptedAttributes } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{ts,tsx}'],
    output: 'locales/{{language}}/{{namespace}}.json',
  },
  lint: {
    // Extend built-in lists with project-specific elements
    acceptedTags: ['my-button', 'app-header', ...recommendedAcceptedTags],
    acceptedAttributes: ['data-label', 'tooltip', ...recommendedAcceptedAttributes],
    ignoredTags: ['pre', 'code', 'kbd'],
    ignoredAttributes: ['data-testid', 'aria-hidden'],
  },
});
```

--------------------------------

### Configure Locize Integration

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Configure integration with the Locize translation management system. Provide your project ID, API key (recommended via environment variables), version, and CDN type.

```javascript
locize: {
    projectId: 'your-project-id',
    apiKey: process.env.LOCIZE_API_KEY,
    version: 'latest',
    cdnType: 'standard'
  }
```

--------------------------------

### Define i18next-cli Configuration

Source: https://context7.com/i18next/i18next-cli/llms.txt

Use defineConfig to create a type-safe configuration object for i18next-cli. This helper provides IntelliSense for all available options, including locale settings, extraction rules, linting, type generation, and Locize integration.

```typescript
import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de', 'fr'],
  extract: {
    input: ['src/**/*.{ts,tsx,js,jsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
    defaultNS: 'translation',
    keySeparator: '.',
    nsSeparator: ':',
    pluralSeparator: '_',
    contextSeparator: '_',
    functions: ['t', '*.t', 'i18next.t'],
    transComponents: ['Trans'],
    useTranslationNames: [
      'useTranslation',
      { name: 'loadPageT', nsArg: 1, keyPrefixArg: 2 },
    ],
    sort: true,
    indentation: 2,
    removeUnusedKeys: true,
    defaultValue: '',
    primaryLanguage: 'en',
    preservePatterns: ['dynamic.*.key', 'assets:*'],
    outputFormat: 'json', // 'json' | 'json5' | 'yaml' | 'ts' | 'js' | 'js-esm' | 'js-cjs'
    warnOnConflicts: 'warn',
    extractFromComments: true,
  },
  lint: {
    ignoredTags: ['pre', 'code'],
    ignoredAttributes: ['data-testid'],
    checkInterpolationParams: true,
  },
  types: {
    input: 'public/locales/en/**/*.json',
    basePath: 'public/locales/en',
    output: 'src/types/i18next.d.ts',
    resourcesFile: 'src/types/resources.d.ts',
    enableSelector: true,
  },
  locize: {
    projectId: 'your-project-id',
    apiKey: process.env.LOCIZE_API_KEY,
    version: 'latest',
  },
  plugins: [],
});
```

--------------------------------

### Find Hardcoded Strings with i18next-cli (Zero Config)

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Identify hardcoded strings in your project without initial configuration.

```bash
npx i18next-cli lint
```

--------------------------------

### Enable Watch Mode for Development

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Run `i18next-cli` in watch mode to automatically update translations as you develop. This applies to both `extract` and `lint` commands.

```bash
npx i18next-cli extract --watch
npx i18next-cli lint --watch
```

--------------------------------

### Plugin System - Plugin Interface

Source: https://context7.com/i18next/i18next-cli/llms.txt

Plugins allow users to hook into the extraction, linting, and instrumentation lifecycle of i18next-cli. They can transform source code, inspect AST nodes, inject custom keys, process lint results, and post-process instrumentation candidates.

```APIDOC
## `Plugin` Interface

### Description
Plugins hook into extraction, linting, and instrumentation via a unified lifecycle interface. A plugin can transform source code before parsing (`onLoad`), inspect every AST node (`onVisitNode`), inject custom keys (`addKey`/`onEnd`), process lint results (`lintOnResult`), and post-process instrumentation candidates (`instrumentOnResult`).

### Plugin Methods
- **`name`** (string): The name of the plugin.
- **`lintExtensions`** (string[]): File extensions to consider for linting.
- **`instrumentExtensions`** (string[]): File extensions to consider for instrumentation.
- **`setup`** (async () => void): One-time initialization function.
- **`onLoad`** (async (code: string, filePath: string) => string | undefined): Transforms source code before parsing.
- **`onVisitNode`** (async (node: any, context: any) => void): Inspects every AST node.
- **`onKeySubmitted`** (async (key: Readonly<ExtractedKey>) => void): Observes every submitted key.
- **`onEnd`** (async (keys: ExtractedKeysMap) => void): Post-processes the complete key map.
- **`afterSync`** (async (results: any, config: any) => void): Runs after translation files are written.
- **`lintOnLoad`** (async (code: string, filePath: string) => string | null | undefined): Preprocesses files for linting.
- **`lintOnResult`** (async (filePath: string, issues: LintIssue[]) => LintIssue[]): Filters linting issues.
- **`instrumentOnResult`** (async (filePath: string, candidates: CandidateString[]) => CandidateString[]): Filters instrumentation candidates.

### Example Usage
```typescript
import { defineConfig } from 'i18next-cli';
import type { Plugin, ExtractedKey, ExtractedKeysMap, LintIssue, CandidateString } from 'i18next-cli';
import { readFile } from 'node:fs/promises';
import { glob } from 'glob';

const vuePlugin = (): Plugin => ({
  name: 'vue-plugin',
  // Extension hints used as optimization skip hints
  lintExtensions: ['.vue'],
  instrumentExtensions: ['.vue'],

  // One-time initialization
  setup: async () => {
    console.log('Vue plugin initialized');
  },

  // Transform .vue files to JS/TSX before SWC parses them
  onLoad: async (code, filePath) => {
    if (!filePath.endsWith('.vue')) return undefined; // pass through
    const scriptMatch = code.match(/<script[^>]*>([\s\S]*?)<\/script>/);
    return scriptMatch ? scriptMatch[1] : code;
  },

  // Inject custom scope info for a proprietary hook (e.g. usePageT)
  onVisitNode: (node, context) => {
    if (
      node.type === 'VariableDeclarator' &&
      (node as any).init?.type === 'CallExpression' &&
      (node as any).init?.callee?.value === 'usePageT'
    ) {
      context.setVarInScope('t', { defaultNs: 'pages', keyPrefix: 'dashboard' });
    }
  },

  // Observe every submitted key (read-only snapshot)
  onKeySubmitted: (key: Readonly<ExtractedKey>) => {
    if (key.ns === 'banned') console.warn(`Banned namespace used: ${key.key}`);
  },

  // Post-process the complete key map (add non-JS keys from .vue templates)
  onEnd: async (keys: ExtractedKeysMap) => {
    const vueFiles = await glob('src/**/*.vue');
    for (const file of vueFiles) {
      const content = await readFile(file, 'utf-8');
      for (const [, key] of content.matchAll(/\$t\('([^']+)'\)/g)) {
        keys.set(`translation:${key}`, { key, ns: 'translation', defaultValue: key });
      }
    }
  },

  // Run after translation files are written
  afterSync: async (results, config) => {
    const updatedCount = results.filter(r => r.updated).length;
    console.log(`${updatedCount} translation files updated.`);
  },

  // Lint: preprocess .vue files
  lintOnLoad: async (code, filePath) => {
    if (!filePath.endsWith('.vue')) return undefined;
    const match = code.match(/<template>([\s\S]*?)<\/template>/);
    return match ? match[1] : null; // null = skip file
  },

  // Lint: filter issues
  lintOnResult: async (filePath, issues: LintIssue[]) => {
    return issues.filter(i => i.type !== 'interpolation'); // keep only hardcoded
  },

  // Instrument: only process high-confidence candidates
  instrumentOnResult: async (filePath, candidates: CandidateString[]) => {
    return candidates.filter(c => c.confidence >= 0.7);
  },
});

export default defineConfig({
  locales: ['en', 'de'],
  extract: { input: ['src/**/*.{ts,tsx,vue}'], output: 'locales/{{language}}/{{namespace}}.json' },
  plugins: [vuePlugin()],
});
```
```

--------------------------------

### Locize sync command options

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

The `locize-sync` command supports additional options to customize the synchronization process. Use `--dry-run` to preview changes without making any modifications.

```bash
npx i18next-cli locize-sync [options]
```

--------------------------------

### Run i18next-cli Instrument

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Execute the instrument command to scan and transform user-facing strings into i18next translation calls. This is a first-pass tool and requires careful review of suggested transformations.

```bash
npx i18next-cli instrument
```

--------------------------------

### i18next Function Calls with returnObjects

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Demonstrates how to retrieve structured content (objects) instead of just strings by setting `returnObjects: true`.

```javascript
// With structured content (returnObjects)
t('countries', { returnObjects: true });
```

--------------------------------

### Migrate Legacy i18next-parser Config

Source: https://context7.com/i18next/i18next-cli/llms.txt

Migrate a configuration file from the legacy i18next-parser format to the i18next-cli format. You can specify the path to the legacy config file.

```bash
npx i18next-cli migrate-config
```

```bash
npx i18next-cli migrate-config i18next-parser.config.mjs
```

--------------------------------

### Selector API with Single Namespace

Source: https://github.com/i18next/i18next-cli/blob/main/README.md

Illustrates using the Selector API with a single namespace hook. Paths are extracted directly into the bound namespace.

```ts
const { t } = useTranslation('common');

t(
  ($) => $.button.save
);                  // → common.json: button.save
t(
  ($) => $.button.save, { ns: 'auth' }
);  // → auth.json:   button.save
```