> Documentation index: [llms.txt](https://www.i18next.com/llms.txt). Every page is also available as Markdown at its URL plus `.md`.

# Programmatic usage

Run extraction, linting and the other commands from a build script or any Node.js program.

In addition to the CLI commands, `i18next-cli` can be used programmatically in your build scripts, Gulp tasks, or any Node.js application.

## Basic programmatic usage

```typescript
import {
  runExtractor,
  runLinter,
  runSyncer,
  runStatus,
  runTypesGenerator,
} 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',
  },
};

// Run the complete extraction process
const { anyFileUpdated, hasErrors } = await runExtractor(config);
console.log('Files updated:', anyFileUpdated);

// Print the translation status (exits the process with code 1 when
// translations are missing)
await runStatus(config);

// Run linting and get results
const { success, message, files } = await runLinter(config);
if (!success) {
  console.error(message);
  for (const [filename, issues] of Object.entries(files)) {
    console.error(`${issues.length} issues found in ${filename}.`);
  }
}

// Sync translation files
await runSyncer(config);

// types generation
await runTypesGenerator(config);
```

## Build tool integration

### Gulp

```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);
});
```

### Webpack

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

class I18nextExtractionPlugin {
  apply(compiler) {
    compiler.hooks.afterEmit.tapAsync(
      'I18nextExtractionPlugin',
      async (compilation, callback) => {
        await runExtractor(config);
        callback();
      }
    );
  }
}
```

## Available functions

- `runExtractor(config, options?)`: Complete extraction with file writing
- `runLinter(config)`: Run linting analysis and return results
- `runSyncer(config)`: Sync translation files
- `runStatus(config, options?)`: Print the translation status; exits the process with code 1 when translations are missing
- `runTypesGenerator(config)`: Generate types
- `runLocalize(options?, configPath?)`: The full [`localize`](https://www.i18next.com/cli/commands/localize.md) flow (detect → instrument → extract → Locize sync with auto-translate → download)

## Advanced usage

### `Linter`: a class that lints your codebase and emits events along the way

```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.on('progress', ({ message }) => console.log(message));

await linter.run();
```

This programmatic API gives you the same power as the CLI but with full control over when and how it runs in your build process.
