0
# CLI Extraction Tools
1

2
Command-line tools and programmatic APIs for extracting translatable strings from TypeScript source code.
3

4
## Capabilities
5

6
### CLI Main Function
7

8
The main entry point for the ngx-extractor command-line tool.
9

10
```typescript { .api }
11
/**
12
 * Main CLI entry point for the ngx-extractor tool
13
 * Processes command line arguments and executes string extraction
14
 * @param args - Command line arguments array
15
 * @returns Process exit code (0 for success, non-zero for errors)
16
 */
17
function main(args: string[]): number;
18
```
19

20
**CLI Usage:**
21

22
```bash
23
# Extract strings to XLIFF format
24
ngx-extractor -i "src/**/*.ts" -o src/i18n/messages.xlf -f xlf -l en
25

26
# Extract strings to XLIFF2 format  
27
ngx-extractor -i "src/**/*.ts" -o src/i18n/messages.xlf2 -f xlf2
28

29
# Extract strings to XMB format
30
ngx-extractor -i "src/**/*.ts" -o src/i18n/messages.xmb -f xmb
31

32
# Multiple input paths
33
ngx-extractor -i "src/**/*.ts" -i "lib/**/*.ts" -o messages.xlf
34
```
35

36
**CLI Options:**
37
- `-i, --input` - Input file paths to extract strings from (supports glob patterns, can be specified multiple times)
38
- `-o, --out-file` - Output file path for extracted translation file (required)
39
- `-f, --format` - Output format: "xlf", "xlf2", or "xmb" (default: "xlf")
40
- `-l, --locale` - Source language/locale of the application (default: "en")
41

42
### AST Extraction Function
43

44
Core function that extracts translatable strings from TypeScript source files.
45

46
```typescript { .api }
47
/**
48
 * Extracts translatable strings from TypeScript files by parsing AST
49
 * Searches for I18n service calls and extracts string literals and I18nDef objects
50
 * @param paths - Array of file paths to process (supports glob patterns)
51
 * @returns Object mapping file URLs to arrays of extracted messages
52
 */
53
function getAst(paths: string[]): {[url: string]: (string | I18nDef)[]};
54
```
55

56
**Usage Example:**
57

58
```typescript
59
import { getAst } from "@ngx-translate/i18n-polyfill/extractor";
60

61
// Extract from specific files
62
const messages = getAst(["src/app.component.ts", "src/services/user.service.ts"]);
63

64
// Extract using glob patterns
65
const allMessages = getAst(["src/**/*.ts", "lib/**/*.component.ts"]);
66

67
// Result structure:
68
// {
69
//   "src/app.component.ts": ["Hello world", { value: "Welcome", id: "welcome.msg" }],
70
//   "src/user.service.ts": ["User not found", "Please try again"]
71
// }
72
```
73

74
### Translation File Generator
75

76
Generates translation file content from extracted messages in various formats.
77

78
```typescript { .api }
79
/**
80
 * Generates translation file content from extracted messages
81
 * Supports XLIFF, XLIFF2, and XMB output formats
82
 * @param messages - Extracted messages by file URL
83
 * @param sourcePath - Source file path for the translation file
84
 * @param format - Output format: "xlf", "xlf2", or "xmb" (default: "xlf")
85
 * @param locale - Source locale for the translation file (default: "en")
86
 * @returns Generated translation file content as string
87
 */
88
function getFileContent(
89
  messages: {[url: string]: (string | I18nDef)[]},
90
  sourcePath: string,
91
  format?: string,
92
  locale?: string
93
): string;
94
```
95

96
**Usage Example:**
97

98
```typescript
99
import { getAst, getFileContent } from "@ngx-translate/i18n-polyfill/extractor";
100

101
// Extract messages from source files
102
const extractedMessages = getAst(["src/**/*.ts"]);
103

104
// Generate XLIFF file content
105
const xliffContent = getFileContent(
106
  extractedMessages,
107
  "src/i18n/messages.xlf",
108
  "xlf",
109
  "en"
110
);
111

112
// Generate XLIFF2 file content
113
const xliff2Content = getFileContent(
114
  extractedMessages,
115
  "src/i18n/messages.xlf2", 
116
  "xlf2",
117
  "en"
118
);
119

120
// Write to file
121
require("fs").writeFileSync("messages.xlf", xliffContent);
122
```
123

124
## Extraction Patterns
125

126
The extraction tool recognizes several patterns of I18n service usage:
127

128
### Simple String Calls
129

130
```typescript
131
// Extracted as: "Hello world"
132
this.i18n("Hello world");
133
i18n("Simple message");
134
```
135

136
### Calls with Interpolation
137

138
```typescript  
139
// Extracted as: "Hello {{name}}"
140
this.i18n("Hello {{name}}", { name: userName });
141
```
142

143
### I18nDef Object Calls
144

145
```typescript
146
// Extracted as: { value: "Welcome", id: "welcome.msg", meaning: "greeting", description: "Welcome message" }
147
this.i18n({
148
  value: "Welcome",
149
  id: "welcome.msg", 
150
  meaning: "greeting",
151
  description: "Welcome message"
152
});
153
```
154

155
### Template Literals
156

157
```typescript
158
// Extracted as: "Hello {{name}}, you have {{count}} messages"
159
const message = `Hello {{name}}, you have {{count}} messages`;
160
this.i18n(message, { name, count });
161
```
162

163
### Variable References
164

165
```typescript
166
// Only extracts if the variable value can be statically determined
167
const WELCOME_MSG = "Welcome to our app";
168
this.i18n(WELCOME_MSG);
169
```
170

171
## Binary Installation
172

173
The CLI tool is available as a binary when the package is installed:
174

175
```json
176
{
177
  "bin": {
178
    "ngx-extractor": "extractor/ngx-extractor.js"
179
  },
180
  "scripts": {
181
    "extract": "ngx-extractor -i 'src/**/*.ts' -o src/i18n/messages.xlf"
182
  }
183
}
184
```
185

186
## Integration with Angular i18n
187

188
The extracted translation files are compatible with Angular's standard i18n workflow:
189

190
1. **Extract template messages** using Angular CLI:
191
   ```bash
192
   ng extract-i18n --output-path src/i18n
193
   ```
194

195
2. **Extract code messages** using ngx-extractor:
196
   ```bash  
197
   ngx-extractor -i "src/**/*.ts" -o src/i18n/messages.xlf
198
   ```
199

200
3. **Translate the merged file** and configure Angular for production builds with translated content.
201

202
The tool merges extracted code messages with existing translation files, preserving existing translations while adding new messages that need translation.