or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdindex.mdparser.mdstream.md
tile.json

index.mddocs/

i18next-scanner

i18next-scanner is a comprehensive code scanning tool that extracts internationalization (i18n) translation keys and values from JavaScript and React codebases, specifically designed to work with the i18next ecosystem. It offers both programmatic API and command-line interfaces for parsing source code to identify translation strings, supports React components including the Trans component, and can merge extracted keys with existing translation resources while maintaining context and pluralization information.

Package Information

  • Package Name: i18next-scanner
  • Package Type: npm
  • Language: JavaScript
  • Installation: 
    npm install i18next-scanner
    or 
    npm install -g i18next-scanner

Core Imports

const scanner = require('i18next-scanner');
const { Parser } = require('i18next-scanner');

For ES modules:

import scanner from 'i18next-scanner';
import { Parser } from 'i18next-scanner';

Basic Usage

const fs = require('fs');
const Parser = require('i18next-scanner').Parser;

// Create a parser instance
const parser = new Parser({
  lngs: ['en', 'de'],
  ns: ['translation'],
  defaultNs: 'translation',
  resource: {
    loadPath: 'i18n/{{lng}}/{{ns}}.json',
    savePath: 'i18n/{{lng}}/{{ns}}.json'
  }
});

// Parse translation functions
const content = fs.readFileSync('src/app.js', 'utf-8');
parser.parseFuncFromString(content);

// Parse React Trans components
const jsxContent = fs.readFileSync('src/App.jsx', 'utf-8');
parser.parseTransFromString(jsxContent);

// Get extracted keys
console.log(parser.get());

Architecture

i18next-scanner is built around several key components:

  • Parser Core: The main 
    Parser
    class that handles key extraction, storage, and resource management
  • Transform Stream: Stream-based API for integration with build tools like Gulp and Grunt
  • CLI Interface: Command-line tool for batch processing files with configuration
  • Parsing Engines: Specialized parsers for JavaScript functions, JSX Trans components, and HTML attributes
  • Resource Management: Automatic loading and merging with existing translation files

Capabilities

Parser API

Core parsing functionality for extracting translation keys from source code. Provides methods for parsing function calls, JSX components, and HTML attributes with configurable options.

class Parser {
  constructor(options?: ParserOptions);
  parseFuncFromString(content: string, opts?: ParseOptions, customHandler?: CustomHandler): Parser;
  parseTransFromString(content: string, opts?: ParseOptions, customHandler?: CustomHandler): Parser;
  parseAttrFromString(content: string, opts?: ParseOptions, customHandler?: CustomHandler): Parser;
  get(key?: string, opts?: GetOptions): any;
  get(opts: GetOptions): any; // Overload for options-only call
  set(key: string, options?: SetOptions): Parser;
  set(key: string, defaultValue: string): Parser; // Backward compatibility overload
  toJSON(options?: JSONOptions): string;
  formatResourceLoadPath(lng: string, ns: string): string;
  formatResourceSavePath(lng: string, ns: string): string;
}

Parser API

Transform Stream API

Stream-based interface for processing files in build pipelines. Creates transform streams that can be used with vinyl-fs for file processing.

function createStream(
  options: ParserOptions,
  customTransform?: CustomTransform,
  customFlush?: CustomFlush
): NodeJS.ReadWriteStream;

// Convenience API - default export
function scanner(
  options: ParserOptions,
  customTransform?: CustomTransform,
  customFlush?: CustomFlush
): NodeJS.ReadWriteStream;

Transform Stream

CLI Interface

Command-line tool for scanning files and extracting translation keys. Supports glob patterns, configuration files, and output directory specification.

i18next-scanner [options] <file ...>

Options:
  --config <config>  Path to the config file (default: i18next-scanner.config.js)
  --output <path>    Path to the output directory (default: .)
  -V, --version      output the version number
  -h, --help         output usage information

CLI Usage

Types

interface ParserOptions {
  compatibilityJSON?: 'v1' | 'v2' | 'v3' | 'v4';
  debug?: boolean;
  sort?: boolean;
  attr?: {
    list: string[];
    extensions: string[];
  };
  func?: {
    list: string[];
    extensions: string[];
  };
  trans?: {
    component: string | RegExp;
    i18nKey: string;
    defaultsKey: string;
    extensions: string[];
    fallbackKey?: boolean | ((ns: string, value: string) => string);
    supportBasicHtmlNodes?: boolean;
    keepBasicHtmlNodesFor?: string[];
    acorn?: AcornOptions;
  };
  lngs: string[];
  fallbackLng?: string;
  ns: string | string[];
  defaultLng?: string;
  defaultNs?: string;
  defaultValue?: string;
  resource?: {
    loadPath: string | ((lng: string, ns: string) => string);
    savePath: string | ((lng: string, ns: string) => string);
    jsonIndent?: number;
    lineEnding?: string;
  };
  keySeparator?: string | false;
  nsSeparator?: string | false;
  context?: boolean;
  contextFallback?: boolean;
  contextSeparator?: string;
  contextDefaultValues?: string[];
  plural?: boolean;
  pluralFallback?: boolean;
  pluralSeparator?: string;
  interpolation?: {
    prefix: string;
    suffix: string;
  };
  metadata?: Record<string, any>;
  allowDynamicKeys?: boolean;
  removeUnusedKeys?: boolean | ((lng: string, ns: string, key: string) => boolean);
}

interface ParseOptions {
  list?: string[];
  extensions?: string[];
  transformOptions?: {
    filepath?: string;
  };
  [key: string]: any;
}

interface GetOptions {
  sort?: boolean;
  lng?: string;
}

interface SetOptions {
  defaultValue?: string;
  defaultValue_plural?: string;
  count?: number;
  context?: string;
  ns?: string;
  keySeparator?: string | false;
  nsSeparator?: string | false;
  metadata?: Record<string, any>;
  fallbackKey?: boolean | string | ((ns: string, value: string) => string);
}

interface JSONOptions {
  replacer?: (key: string, value: any) => any;
  space?: string | number;
  sort?: boolean;
  lng?: string;
}

type CustomHandler = (key: string, options: SetOptions) => void;
type CustomTransform = (file: VinylFile, encoding: string, done: () => void) => void;
type CustomFlush = (done: () => void) => void;

interface AcornOptions {
  ecmaVersion?: number;
  sourceType?: 'script' | 'module';
  [key: string]: any;
}