0
# i18next-scanner
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: i18next-scanner
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install i18next-scanner` or `npm install -g i18next-scanner`
10

11
## Core Imports
12

13
```javascript
14
const scanner = require('i18next-scanner');
15
const { Parser } = require('i18next-scanner');
16
```
17

18
For ES modules:
19

20
```javascript
21
import scanner from 'i18next-scanner';
22
import { Parser } from 'i18next-scanner';
23
```
24

25
## Basic Usage
26

27
```javascript
28
const fs = require('fs');
29
const Parser = require('i18next-scanner').Parser;
30

31
// Create a parser instance
32
const parser = new Parser({
33
  lngs: ['en', 'de'],
34
  ns: ['translation'],
35
  defaultNs: 'translation',
36
  resource: {
37
    loadPath: 'i18n/{{lng}}/{{ns}}.json',
38
    savePath: 'i18n/{{lng}}/{{ns}}.json'
39
  }
40
});
41

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

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

50
// Get extracted keys
51
console.log(parser.get());
52
```
53

54
## Architecture
55

56
i18next-scanner is built around several key components:
57

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

64
## Capabilities
65

66
### Parser API
67

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

70
```javascript { .api }
71
class Parser {
72
  constructor(options?: ParserOptions);
73
  parseFuncFromString(content: string, opts?: ParseOptions, customHandler?: CustomHandler): Parser;
74
  parseTransFromString(content: string, opts?: ParseOptions, customHandler?: CustomHandler): Parser;
75
  parseAttrFromString(content: string, opts?: ParseOptions, customHandler?: CustomHandler): Parser;
76
  get(key?: string, opts?: GetOptions): any;
77
  get(opts: GetOptions): any; // Overload for options-only call
78
  set(key: string, options?: SetOptions): Parser;
79
  set(key: string, defaultValue: string): Parser; // Backward compatibility overload
80
  toJSON(options?: JSONOptions): string;
81
  formatResourceLoadPath(lng: string, ns: string): string;
82
  formatResourceSavePath(lng: string, ns: string): string;
83
}
84
```
85

86
[Parser API](./parser.md)
87

88
### Transform Stream API
89

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

92
```javascript { .api }
93
function createStream(
94
  options: ParserOptions,
95
  customTransform?: CustomTransform,
96
  customFlush?: CustomFlush
97
): NodeJS.ReadWriteStream;
98

99
// Convenience API - default export
100
function scanner(
101
  options: ParserOptions,
102
  customTransform?: CustomTransform,
103
  customFlush?: CustomFlush
104
): NodeJS.ReadWriteStream;
105
```
106

107
[Transform Stream](./stream.md)
108

109
### CLI Interface
110

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

113
```bash { .api }
114
i18next-scanner [options] <file ...>
115

116
Options:
117
  --config <config>  Path to the config file (default: i18next-scanner.config.js)
118
  --output <path>    Path to the output directory (default: .)
119
  -V, --version      output the version number
120
  -h, --help         output usage information
121
```
122

123
[CLI Usage](./cli.md)
124

125
## Types
126

127
```javascript { .api }
128
interface ParserOptions {
129
  compatibilityJSON?: 'v1' | 'v2' | 'v3' | 'v4';
130
  debug?: boolean;
131
  sort?: boolean;
132
  attr?: {
133
    list: string[];
134
    extensions: string[];
135
  };
136
  func?: {
137
    list: string[];
138
    extensions: string[];
139
  };
140
  trans?: {
141
    component: string | RegExp;
142
    i18nKey: string;
143
    defaultsKey: string;
144
    extensions: string[];
145
    fallbackKey?: boolean | ((ns: string, value: string) => string);
146
    supportBasicHtmlNodes?: boolean;
147
    keepBasicHtmlNodesFor?: string[];
148
    acorn?: AcornOptions;
149
  };
150
  lngs: string[];
151
  fallbackLng?: string;
152
  ns: string | string[];
153
  defaultLng?: string;
154
  defaultNs?: string;
155
  defaultValue?: string;
156
  resource?: {
157
    loadPath: string | ((lng: string, ns: string) => string);
158
    savePath: string | ((lng: string, ns: string) => string);
159
    jsonIndent?: number;
160
    lineEnding?: string;
161
  };
162
  keySeparator?: string | false;
163
  nsSeparator?: string | false;
164
  context?: boolean;
165
  contextFallback?: boolean;
166
  contextSeparator?: string;
167
  contextDefaultValues?: string[];
168
  plural?: boolean;
169
  pluralFallback?: boolean;
170
  pluralSeparator?: string;
171
  interpolation?: {
172
    prefix: string;
173
    suffix: string;
174
  };
175
  metadata?: Record<string, any>;
176
  allowDynamicKeys?: boolean;
177
  removeUnusedKeys?: boolean | ((lng: string, ns: string, key: string) => boolean);
178
}
179

180
interface ParseOptions {
181
  list?: string[];
182
  extensions?: string[];
183
  transformOptions?: {
184
    filepath?: string;
185
  };
186
  [key: string]: any;
187
}
188

189
interface GetOptions {
190
  sort?: boolean;
191
  lng?: string;
192
}
193

194
interface SetOptions {
195
  defaultValue?: string;
196
  defaultValue_plural?: string;
197
  count?: number;
198
  context?: string;
199
  ns?: string;
200
  keySeparator?: string | false;
201
  nsSeparator?: string | false;
202
  metadata?: Record<string, any>;
203
  fallbackKey?: boolean | string | ((ns: string, value: string) => string);
204
}
205

206
interface JSONOptions {
207
  replacer?: (key: string, value: any) => any;
208
  space?: string | number;
209
  sort?: boolean;
210
  lng?: string;
211
}
212

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

217
interface AcornOptions {
218
  ecmaVersion?: number;
219
  sourceType?: 'script' | 'module';
220
  [key: string]: any;
221
}
222
```