0
# Translation File Serializers
1

2
Serializers for generating translation files in multiple formats: XLIFF, XLIFF2, XMB, and XTB.
3

4
## Capabilities
5

6
### XLIFF Serializer
7

8
Generates XLIFF 1.2 format translation files, the default format used by Angular i18n.
9

10
```typescript { .api }
11
/**
12
 * Generates XLIFF 1.2 format translation file content
13
 * @param messages - Array of i18n messages to serialize
14
 * @param locale - Target locale for the translation file
15
 * @param existingNodes - Optional existing XML nodes to merge with
16
 * @returns XLIFF XML content as string
17
 */
18
function xliffWrite(
19
  messages: i18n.Message[], 
20
  locale: string | null, 
21
  existingNodes?: xml.Node[]
22
): string;
23

24
/**
25
 * Loads XLIFF content and converts to i18n messages
26
 * @param content - XLIFF XML content string
27
 * @returns Object mapping message IDs to translated strings
28
 */
29
function xliffLoadToI18n(content: string): I18nMessagesById;
30

31
/**
32
 * Loads XLIFF content to XML nodes
33
 * @param content - XLIFF XML content string  
34
 * @returns Object mapping message IDs to XML nodes
35
 */
36
function xliffLoadToXml(content: string): XmlMessagesById;
37

38
/**
39
 * Generates digest/hash for XLIFF message identification
40
 * @param message - Message to generate digest for
41
 * @returns Message digest string
42
 */
43
function xliffDigest(message: i18n.Message): string;
44
```
45

46
### XLIFF2 Serializer
47

48
Generates XLIFF 2.0/2.1 format translation files with improved features and structure.
49

50
```typescript { .api }
51
/**
52
 * Generates XLIFF 2.0 format translation file content
53
 * @param messages - Array of i18n messages to serialize
54
 * @param locale - Target locale for the translation file
55
 * @param existingNodes - Optional existing XML nodes to merge with
56
 * @returns XLIFF2 XML content as string
57
 */
58
function xliff2Write(
59
  messages: i18n.Message[], 
60
  locale: string | null, 
61
  existingNodes?: xml.Node[]
62
): string;
63

64
/**
65
 * Loads XLIFF2 content and converts to i18n messages
66
 * @param content - XLIFF2 XML content string
67
 * @returns Object mapping message IDs to translated strings
68
 */
69
function xliff2LoadToI18n(content: string): I18nMessagesById;
70

71
/**
72
 * Loads XLIFF2 content to XML nodes
73
 * @param content - XLIFF2 XML content string
74
 * @returns Object mapping message IDs to XML nodes
75
 */
76
function xliff2LoadToXml(content: string): XmlMessagesById;
77

78
/**
79
 * Generates digest/hash for XLIFF2 message identification
80
 * @param message - Message to generate digest for
81
 * @returns Message digest string
82
 */
83
function xliff2Digest(message: i18n.Message): string;
84
```
85

86
### XMB Serializer
87

88
Generates XMB (XML Message Bundle) format files, Angular's internal message bundle format.
89

90
```typescript { .api }
91
/**
92
 * Generates XMB format translation file content
93
 * @param messages - Array of i18n messages to serialize
94
 * @param locale - Target locale for the translation file
95
 * @param existingNodes - Optional existing XML nodes to merge with
96
 * @returns XMB XML content as string
97
 */
98
function xmbWrite(
99
  messages: i18n.Message[], 
100
  locale: string | null, 
101
  existingNodes?: xml.Node[]
102
): string;
103

104
/**
105
 * Loads XMB content to XML nodes
106
 * @param content - XMB XML content string
107
 * @returns Object mapping message IDs to XML nodes
108
 */
109
function xmbLoadToXml(content: string): XmlMessagesById;
110

111
/**
112
 * Generates digest/hash for XMB message identification
113
 * @param message - Message to generate digest for
114
 * @returns Message digest string
115
 */
116
function xmbDigest(message: i18n.Message): string;
117

118
/**
119
 * Creates placeholder mapper for XMB format
120
 * @param message - Message to create mapper for
121
 * @returns Placeholder mapper instance
122
 */
123
function xmbMapper(message: i18n.Message): PlaceholderMapper;
124
```
125

126
### XTB Serializer
127

128
Handles XTB (XML Translation Bundle) format, used for translated message files.
129

130
```typescript { .api }
131
/**
132
 * Loads XTB content and converts to i18n messages
133
 * @param content - XTB XML content string
134
 * @returns Object mapping message IDs to translated strings
135
 */
136
function xtbLoadToI18n(content: string): I18nMessagesById;
137

138
/**
139
 * Generates digest/hash for XTB message identification
140
 * @param message - Message to generate digest for
141
 * @returns Message digest string
142
 */
143
function xtbDigest(message: i18n.Message): string;
144

145
/**
146
 * Creates placeholder mapper for XTB format
147
 * @param message - Message to create mapper for
148
 * @returns Placeholder mapper instance
149
 */
150
function xtbMapper(message: i18n.Message): PlaceholderMapper;
151
```
152

153
### Core Serializer Utilities
154

155
Common utilities used across all serializer formats.
156

157
```typescript { .api }
158
/**
159
 * Serializes HTML nodes to string with locale-specific formatting
160
 * @param nodes - HTML nodes to serialize
161
 * @param locale - Target locale string
162
 * @param params - Interpolation parameters
163
 * @returns Array of serialized node strings
164
 */
165
function serializeNodes(
166
  nodes: html.Node[], 
167
  locale: string, 
168
  params: {[key: string]: any}
169
): string[];
170

171
/**
172
 * Default placeholder mapper implementation
173
 */  
174
class SimplePlaceholderMapper implements PlaceholderMapper {
175
  constructor(message: i18n.Message, placeholderNames: string[]);
176
  toPublicName(internalName: string): string | null;
177
  toInternalName(publicName: string): string | null;
178
}
179
```
180

181
## Format Comparison
182

183
| Feature | XLIFF 1.2 | XLIFF 2.0 | XMB | XTB |
184
|---------|-----------|-----------|-----|-----|
185
| **Use Case** | Standard translation exchange | Modern translation exchange | Angular source messages | Angular translated messages |
186
| **File Extension** | .xlf | .xlf2 | .xmb | .xtb |  
187
| **Angular Default** | ✅ Yes | ❌ No | ❌ No | ❌ No |
188
| **Industry Standard** | ✅ Yes | ✅ Yes | ❌ No | ❌ No |
189
| **Translation Memory** | ✅ Yes | ✅ Yes | ❌ No | ❌ No |
190
| **Metadata Support** | ✅ Good | ✅ Excellent | ✅ Basic | ✅ Basic |
191
192
## Usage Examples
193

194
### Basic XLIFF Generation
195

196
```typescript
197
import { xliffWrite } from "@ngx-translate/i18n-polyfill/serializers";
198
import { MessageBundle } from "@ngx-translate/i18n-polyfill/extractor";
199

200
// Create message bundle and add messages
201
const bundle = new MessageBundle("en");
202
bundle.updateFromTemplate("Hello {{name}}", "app.component.ts");
203
bundle.updateFromTemplate({
204
  value: "Welcome to our app",
205
  id: "welcome.message",
206
  description: "Main welcome message"
207
}, "app.component.ts");
208

209
// Generate XLIFF content
210
const messages = bundle.getMessages();
211
const xliffContent = xliffWrite(messages, "en");
212

213
console.log(xliffContent);
214
// Output: XLIFF XML with translation units
215
```
216

217
### Loading and Merging Translation Files
218

219
```typescript
220
import { xliffLoadToI18n, xliffWrite } from "@ngx-translate/i18n-polyfill/serializers";
221

222
// Load existing translations
223
const existingTranslations = xliffLoadToI18n(existingXliffContent);
224

225
// Add new messages and merge
226
const newMessages = extractedMessagesFromCode;
227
const mergedContent = xliffWrite(newMessages, "en", existingNodes);
228
```
229

230
### Multi-Format Export
231

232
```typescript
233
import { xliffWrite, xliff2Write, xmbWrite } from "@ngx-translate/i18n-polyfill/serializers";
234

235
// Export same messages to different formats
236
const messages = bundle.getMessages();
237

238
const xliffOutput = xliffWrite(messages, "en");
239
const xliff2Output = xliff2Write(messages, "en");  
240
const xmbOutput = xmbWrite(messages, "en");
241

242
// Save to different files
243
fs.writeFileSync("messages.xlf", xliffOutput);
244
fs.writeFileSync("messages.xlf2", xliff2Output);
245
fs.writeFileSync("messages.xmb", xmbOutput);
246
```
247

248
## Message Digests
249

250
Each format uses digest functions to generate unique identifiers for messages:
251

252
- **Purpose**: Stable message IDs that remain consistent across extractions
253
- **Algorithm**: Based on message content, meaning, and description
254
- **Usage**: Links source messages to their translations across different files
255

256
```typescript
257
import { xliffDigest, xliff2Digest, xmbDigest } from "@ngx-translate/i18n-polyfill/serializers";
258

259
const message = createI18nMessage("Hello {{name}}", "greeting");
260

261
const xliffId = xliffDigest(message);    // e.g., "2345678901234567890"
262
const xliff2Id = xliff2Digest(message);  // e.g., "3456789012345678901" 
263
const xmbId = xmbDigest(message);        // e.g., "4567890123456789012"
264
```
265

266
## Placeholder Mapping
267

268
XMB and XTB formats use placeholder mappers to handle interpolation parameters:
269

270
```typescript
271
import { xmbMapper, xtbMapper } from "@ngx-translate/i18n-polyfill/serializers";
272

273
const message = createI18nMessage("Hello {{name}}, you have {{count}} items");
274
const mapper = xmbMapper(message);
275

276
// Map internal placeholder names to public names
277
const publicName = mapper.toPublicName("INTERPOLATION");     // "name"
278
const internalName = mapper.toInternalName("count");          // "INTERPOLATION_1"
279
```