0
# @ngx-translate/i18n-polyfill
1

2
@ngx-translate/i18n-polyfill is a speculative polyfill that provides comprehensive i18n code translation support for Angular applications. It bridges the gap until native Angular i18n code translation support is available, offering both runtime translation services and powerful CLI extraction tools with support for multiple translation formats.
3

4
## Package Information
5

6
- **Package Name**: @ngx-translate/i18n-polyfill
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ngx-translate/i18n-polyfill`
10

11
## Core Imports
12

13
```typescript
14
// Runtime translation service
15
import { I18n, I18nDef, MISSING_TRANSLATION_STRATEGY } from "@ngx-translate/i18n-polyfill";
16

17
// CLI extraction tools
18
import { getAst, getFileContent, MessageBundle } from "@ngx-translate/i18n-polyfill/extractor";
19

20
// Serializers for different formats
21
import { xliffWrite, xliff2Write, xmbWrite } from "@ngx-translate/i18n-polyfill/serializers";
22

23
// Parser utilities
24
import { HtmlParser, TranslationBundle } from "@ngx-translate/i18n-polyfill/parser";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { I18n, I18nDef, MISSING_TRANSLATION_STRATEGY } = require("@ngx-translate/i18n-polyfill");
31
const { getAst, getFileContent } = require("@ngx-translate/i18n-polyfill/extractor");
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { I18n, I18nDef } from "@ngx-translate/i18n-polyfill";
38
import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID } from "@angular/core";
39

40
// Configure providers in your Angular module
41
@NgModule({
42
  providers: [
43
    I18n,
44
    { provide: TRANSLATIONS, useValue: translationsContent },
45
    { provide: TRANSLATIONS_FORMAT, useValue: "xlf" },
46
    { provide: LOCALE_ID, useValue: "en" }
47
  ]
48
})
49
export class AppModule {}
50

51
// Use in components or services
52
@Component({...})
53
export class MyComponent {
54
  constructor(private i18n: I18n) {}
55

56
  translate() {
57
    // Simple string translation
58
    const hello = this.i18n("Hello world");
59
    
60
    // Translation with interpolation
61
    const greeting = this.i18n("Hello {{name}}", { name: "John" });
62
    
63
    // Translation with metadata
64
    const message = this.i18n({
65
      value: "Hello {{name}}",
66
      id: "greeting.hello",
67
      meaning: "A friendly greeting",
68
      description: "Greeting message shown to users"
69
    }, { name: "John" });
70
  }
71
}
72
```
73

74
## Architecture
75

76
@ngx-translate/i18n-polyfill is built around several key components:
77

78
- **Runtime Translation Service**: Injectable Angular service (`I18n`) for synchronous code-based translations
79
- **CLI Extraction Tools**: Command-line utilities for extracting translatable strings from TypeScript source code
80
- **Multi-Format Support**: Serializers for XLIFF, XLIFF2, XMB, and XTB translation file formats
81
- **AST Processing**: Advanced Abstract Syntax Tree parsing for accurate string extraction
82
- **Translation Bundle Management**: Efficient loading and processing of translation files at runtime
83

84
## Capabilities
85

86
### Translation Runtime Service
87

88
Injectable Angular service providing synchronous code-based translations with support for interpolations and ICU expressions.
89

90
```typescript { .api }
91
@Injectable()
92
class I18n {
93
  constructor(
94
    format: string,
95
    translations: string,
96
    locale: string,
97
    missingTranslationStrategy?: MissingTranslationStrategy
98
  );
99
  
100
  (def: string | I18nDef, params?: {[key: string]: any}): string;
101
}
102
```
103

104
[Translation Service](./translation-service.md)
105

106
### CLI String Extraction
107

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

110
```typescript { .api }
111
function main(args: string[]): number;
112
function getAst(paths: string[]): {[url: string]: (string | I18nDef)[]};
113
function getFileContent(
114
  messages: {[url: string]: (string | I18nDef)[]},
115
  sourcePath: string,
116
  format?: string,
117
  locale?: string
118
): string;
119
```
120

121
[CLI Extraction Tools](./cli-extraction.md)
122

123
### Translation File Serializers
124

125
Serializers for multiple translation file formats including XLIFF, XLIFF2, XMB, and XTB.
126

127
```typescript { .api }
128
function xliffWrite(messages: i18n.Message[], locale: string | null, existingNodes?: xml.Node[]): string;
129
function xliff2Write(messages: i18n.Message[], locale: string | null, existingNodes?: xml.Node[]): string;
130
function xmbWrite(messages: i18n.Message[], locale: string | null, existingNodes?: xml.Node[]): string;
131
```
132

133
[Serializers](./serializers.md)
134

135
### Message Bundle Management
136

137
Manages i18n message collections with support for template processing and message extraction.
138

139
```typescript { .api }
140
class MessageBundle {
141
  constructor(locale?: string | null);
142
  updateFromTemplate(template: string | I18nDef, url: string): i18n.Message[];
143
  getMessages(): i18n.Message[];
144
  write(write, digest, xmlMessagesById?, createMapper?, filterSources?): string;
145
}
146
```
147

148
[Message Bundle](./message-bundle.md)
149

150
## Types
151

152
```typescript { .api }
153
interface I18nDef {
154
  /** The translatable text content */
155
  value: string;
156
  /** Optional unique identifier for the message */
157
  id?: string;
158
  /** Optional meaning/context for translators */
159
  meaning?: string;
160
  /** Optional description for translators */
161
  description?: string;
162
}
163

164
interface I18n {
165
  (def: string | I18nDef, params?: {[key: string]: any}): string;
166
}
167

168
interface I18nMessagesById {
169
  [msgId: string]: string;
170
}
171

172
interface XmlMessagesById {
173
  [id: string]: xml.Node;
174
}
175

176
interface PlaceholderMapper {
177
  toPublicName(internalName: string): string | null;
178
  toInternalName(publicName: string): string | null;
179
}
180

181
interface MessageMetadata {
182
  meaning?: string;
183
  description?: string;
184
  id?: string;
185
}
186

187
const MISSING_TRANSLATION_STRATEGY: InjectionToken<MissingTranslationStrategy>;
188
```
189

190
## Supported Translation Formats
191

192
- **XLIFF (.xlf)** - Default XML Localization Interchange File Format
193
- **XLIFF 2.0 (.xlf2)** - Updated XLIFF specification
194
- **XTB** - Chrome extension translation format  
195
- **XMB** - Angular message bundle format
196

197
## Angular Integration
198

199
The I18n service integrates with Angular's dependency injection system and requires several providers:
200

201
```typescript
202
import { TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID, MissingTranslationStrategy } from "@angular/core";
203
import { I18n, MISSING_TRANSLATION_STRATEGY } from "@ngx-translate/i18n-polyfill";
204

205
@NgModule({
206
  providers: [
207
    I18n,
208
    { provide: TRANSLATIONS, useValue: translationFileContent },
209
    { provide: TRANSLATIONS_FORMAT, useValue: "xlf" },
210
    { provide: LOCALE_ID, useValue: "en" },
211
    { provide: MISSING_TRANSLATION_STRATEGY, useValue: MissingTranslationStrategy.Warning }
212
  ]
213
})
214
export class AppModule {}
215
```
216

217
The service supports interpolation with named parameters and ICU expressions for advanced pluralization and selection scenarios, matching the functionality available in Angular template translations.