0
# Internationalization
1

2
Multi-language support system for localizing TypeDoc's output interface and messages, enabling documentation generation in multiple languages with full translation support.
3

4
## Capabilities
5

6
### Internationalization Class
7

8
Main internationalization manager that handles locale management, translation loading, and language switching.
9

10
```typescript { .api }
11
/**
12
 * Internationalization manager for multi-language support
13
 */
14
class Internationalization {
15
  /** Current locale */
16
  readonly locale: string;
17
  /** Available translations */
18
  readonly translations: Map<string, Partial<TranslatableStrings>>;
19
  
20
  /**
21
   * Set active locale
22
   * @param locale - Locale code (e.g., "en", "de", "ja")
23
   */
24
  setLocale(locale: string): void;
25
  
26
  /**
27
   * Reset to default locale (English)
28
   */
29
  resetLocale(): void;
30
  
31
  /**
32
   * Add translations for a specific locale
33
   * @param locale - Locale code
34
   * @param translations - Translation strings
35
   */
36
  addTranslations(locale: string, translations: Partial<TranslatableStrings>): void;
37
  
38
  /**
39
   * Get translation proxy for current locale
40
   * @returns Translation proxy with type-safe access
41
   */
42
  proxy(): TranslationProxy;
43
  
44
  /**
45
   * Check if locale is supported
46
   * @param locale - Locale code to check
47
   * @returns True if locale has translations
48
   */
49
  hasLocale(locale: string): boolean;
50
  
51
  /**
52
   * Get available locales
53
   * @returns Array of supported locale codes
54
   */
55
  getAvailableLocales(): string[];
56
}
57
```
58

59
**Usage Examples:**
60

61
```typescript
62
import { Application, Internationalization } from "typedoc";
63

64
const app = await Application.bootstrap({
65
  entryPoints: ["src/index.ts"],
66
  lang: "de", // Set German locale
67
});
68

69
const i18n = app.internationalization;
70

71
// Check current locale
72
console.log(`Current locale: ${i18n.locale}`);
73

74
// Add custom translations
75
i18n.addTranslations("de", {
76
  theme_implements: "Implementiert",
77
  theme_extended_by: "Erweitert von",
78
  theme_type_declaration: "Typ-Deklaration",
79
});
80

81
// Switch locale dynamically
82
i18n.setLocale("ja");
83
console.log(`Switched to: ${i18n.locale}`);
84

85
// Get translation proxy
86
const translations = i18n.proxy();
87
console.log(translations.theme_implements); // Returns localized string
88
```
89

90
### Translation Function
91

92
Core translation function for converting translation keys to localized strings.
93

94
```typescript { .api }
95
/**
96
 * Main translation function
97
 * @param key - Translation key
98
 * @param args - Optional arguments for string interpolation
99
 * @returns Localized string
100
 */
101
function i18n(key: TranslatedString, ...args: any[]): string;
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { i18n } from "typedoc";
108

109
// Basic translation
110
const implementsText = i18n("theme_implements");
111

112
// Translation with arguments
113
const parameterText = i18n("theme_parameter_name", "userId");
114

115
// Dynamic translation in templates
116
function renderProperty(property: any) {
117
  return `
118
    <div class="property">
119
      <h3>${property.name}</h3>
120
      <span class="type-label">${i18n("theme_type")}</span>
121
      <span class="type">${property.type}</span>
122
    </div>
123
  `;
124
}
125
```
126

127
### Translation Types
128

129
Type-safe translation system with strongly-typed translation keys and proxy access.
130

131
```typescript { .api }
132
/**
133
 * Type-safe translation string marker
134
 */
135
type TranslatedString = string & { __translatedBrand: never };
136

137
/**
138
 * Translation proxy providing type-safe access to translations
139
 */
140
interface TranslationProxy {
141
  /** Theme and UI translations */
142
  theme_implements: string;
143
  theme_indexable: string;
144
  theme_type_declaration: string;
145
  theme_constructor: string;
146
  theme_property: string;
147
  theme_method: string;
148
  theme_call_signature: string;
149
  theme_type_alias: string;
150
  theme_variable: string;
151
  theme_function: string;
152
  theme_module: string;
153
  theme_namespace: string;
154
  theme_class: string;
155
  theme_interface: string;
156
  theme_enum: string;
157
  theme_enum_member: string;
158
  theme_parameter: string;
159
  theme_type_parameter: string;
160
  theme_accessor: string;
161
  theme_get_signature: string;
162
  theme_set_signature: string;
163
  theme_reference: string;
164
  theme_document: string;
165
  
166
  /** Documentation structure */
167
  theme_hierarchy: string;
168
  theme_hierarchy_view: string;
169
  theme_on_this_page: string;
170
  theme_search: string;
171
  theme_menu: string;
172
  theme_copy_link: string;
173
  theme_permalink: string;
174
  theme_in: string;
175
  theme_generated_using_typedoc: string;
176
  
177
  /** Type information */
178
  theme_type: string;
179
  theme_value: string;
180
  theme_default_value: string;
181
  theme_inherited_from: string;
182
  theme_overrides: string;
183
  theme_implementation_of: string;
184
  theme_extended_by: string;
185
  theme_extended_types: string;
186
  theme_implemented_by: string;
187
  theme_implemented_types: string;
188
  
189
  /** Parameter and signature info */
190
  theme_parameters: string;
191
  theme_parameter_name: string;
192
  theme_returns: string;
193
  theme_type_parameters: string;
194
  theme_type_parameter_constraint: string;
195
  theme_type_parameter_default: string;
196
  
197
  /** Source and location */
198
  theme_defined_in: string;
199
  theme_source: string;
200
  
201
  /** Flags and modifiers */
202
  theme_optional: string;
203
  theme_readonly: string;
204
  theme_static: string;
205
  theme_private: string;
206
  theme_protected: string;
207
  theme_public: string;
208
  theme_abstract: string;
209
  theme_const: string;
210
  theme_rest: string;
211
  
212
  /** Navigation */
213
  theme_loading: string;
214
  theme_preparing_search_index: string;
215
  theme_search_results: string;
216
  theme_no_results_found: string;
217
  
218
  /** Settings and options */
219
  theme_settings: string;
220
  theme_member_visibility: string;
221
  theme_theme: string;
222
  theme_os: string;
223
  theme_light: string;
224
  theme_dark: string;
225
  theme_auto: string;
226
  
227
  /** Categories and grouping */
228
  kind_project: string;
229
  kind_module: string;
230
  kind_namespace: string;
231
  kind_enum: string;
232
  kind_enum_member: string;
233
  kind_variable: string;
234
  kind_function: string;
235
  kind_class: string;
236
  kind_interface: string;
237
  kind_constructor: string;
238
  kind_property: string;
239
  kind_method: string;
240
  kind_call_signature: string;
241
  kind_index_signature: string;
242
  kind_constructor_signature: string;
243
  kind_parameter: string;
244
  kind_type_literal: string;
245
  kind_type_parameter: string;
246
  kind_accessor: string;
247
  kind_get_signature: string;
248
  kind_set_signature: string;
249
  kind_object_literal: string;
250
  kind_type_alias: string;
251
  kind_reference: string;
252
  kind_document: string;
253
  
254
  /** Error messages */
255
  failed_to_find_packages: string;
256
  found_packages: string;
257
  no_entry_points_provided: string;
258
  unable_to_find_any_entry_points: string;
259
  provided_tsconfig_invalid: string;
260
  
261
  /** Reflection flags */
262
  flag_private: string;
263
  flag_protected: string;
264
  flag_public: string;
265
  flag_static: string;
266
  flag_external: string;
267
  flag_optional: string;
268
  flag_rest: string;
269
  flag_abstract: string;
270
  flag_const: string;
271
  flag_readonly: string;
272
  flag_inherited: string;
273
}
274

275
/**
276
 * Complete interface of all translatable strings in TypeDoc
277
 */
278
interface TranslatableStrings extends TranslationProxy {
279
  // Additional strings not included in proxy for internal use
280
  [key: string]: string;
281
}
282
```
283

284
### Built-in Locale Support
285

286
TypeDoc includes built-in translations for several languages.
287

288
```typescript { .api }
289
/**
290
 * Built-in supported locales
291
 */
292
type SupportedLocales = 
293
  | "en"    // English (default)
294
  | "de"    // German  
295
  | "ja"    // Japanese
296
  | "ko"    // Korean
297
  | "zh"    // Chinese (Simplified);
298
```
299

300
**Usage Examples:**
301

302
```typescript
303
import { Application } from "typedoc";
304

305
// Generate documentation in German
306
const app = await Application.bootstrap({
307
  entryPoints: ["src/index.ts"],
308
  out: "docs-de",
309
  lang: "de",
310
});
311

312
// Generate documentation in Japanese
313
const japaneseApp = await Application.bootstrap({
314
  entryPoints: ["src/index.ts"], 
315
  out: "docs-ja",
316
  lang: "ja",
317
});
318

319
// Check what locales are available
320
const i18n = app.internationalization;
321
console.log("Available locales:", i18n.getAvailableLocales());
322
```
323

324
### Custom Translation Loading
325

326
System for loading and managing custom translations from external sources.
327

328
```typescript { .api }
329
/**
330
 * Utility functions for translation management
331
 */
332
namespace TranslationUtils {
333
  /**
334
   * Add translations from JSON file
335
   * @param i18n - Internationalization instance
336
   * @param locale - Target locale
337
   * @param filePath - Path to JSON translation file
338
   */
339
  function addTranslationsFromFile(
340
    i18n: Internationalization,
341
    locale: string,
342
    filePath: string
343
  ): Promise<void>;
344
  
345
  /**
346
   * Load translations from directory structure
347
   * @param i18n - Internationalization instance
348
   * @param translationsDir - Directory containing locale subdirectories
349
   */
350
  function loadTranslationsFromDirectory(
351
    i18n: Internationalization,
352
    translationsDir: string
353
  ): Promise<void>;
354
  
355
  /**
356
   * Validate translation completeness
357
   * @param translations - Translation object to validate
358
   * @param requiredKeys - Required translation keys
359
   * @returns Array of missing keys
360
   */
361
  function validateTranslations(
362
    translations: Partial<TranslatableStrings>,
363
    requiredKeys: (keyof TranslatableStrings)[]
364
  ): string[];
365
}
366
```
367

368
**Usage Examples:**
369

370
```typescript
371
import { Application, TranslationUtils } from "typedoc";
372
import { writeFile, mkdir } from "fs/promises";
373

374
// Create custom translation file
375
const customTranslations = {
376
  theme_implements: "Реализует",
377
  theme_extended_by: "Расширяется",
378
  theme_type_declaration: "Объявление типа",
379
  theme_constructor: "Конструктор",
380
  theme_property: "Свойство",
381
  theme_method: "Метод",
382
  // ... more Russian translations
383
};
384

385
await mkdir("translations", { recursive: true });
386
await writeFile("translations/ru.json", JSON.stringify(customTranslations, null, 2));
387

388
// Load custom translations
389
const app = await Application.bootstrap();
390
await TranslationUtils.addTranslationsFromFile(
391
  app.internationalization,
392
  "ru", 
393
  "translations/ru.json"
394
);
395

396
// Set to custom locale
397
app.internationalization.setLocale("ru");
398

399
// Generate Russian documentation
400
const project = await app.convert();
401
if (project) {
402
  await app.generateDocs(project, "docs-ru");
403
}
404
```
405

406
### Translation in Custom Themes
407

408
Integration of internationalization in custom themes and templates.
409

410
```typescript { .api }
411
/**
412
 * Theme context with internationalization support
413
 */
414
interface ThemedRenderContext {
415
  /** Translation function bound to current locale */
416
  i18n: (key: TranslatedString, ...args: any[]) => string;
417
  /** Translation proxy for type-safe access */
418
  translations: TranslationProxy;
419
  /** Current locale code */
420
  locale: string;
421
}
422
```
423

424
**Usage Examples:**
425

426
```typescript
427
import { DefaultTheme, i18n } from "typedoc";
428

429
class LocalizedTheme extends DefaultTheme {
430
  render(page: PageEvent<Reflection>, template: RenderTemplate<PageEvent<Reflection>>): string {
431
    // Add translation context to page
432
    const localizedPage = {
433
      ...page,
434
      i18n,
435
      translations: this.context.application.internationalization.proxy(),
436
      locale: this.context.application.internationalization.locale,
437
    };
438
    
439
    return super.render(localizedPage, template);
440
  }
441
}
442

443
// Custom template with translations
444
function renderClassPage(page: PageEvent<DeclarationReflection>) {
445
  const { reflection, i18n } = page;
446
  
447
  return `
448
    <div class="class-page">
449
      <h1>${reflection.name}</h1>
450
      
451
      ${reflection.implementedTypes?.length ? `
452
        <section>
453
          <h2>${i18n("theme_implements")}</h2>
454
          <ul>
455
            ${reflection.implementedTypes.map(type => 
456
              `<li>${type.toString()}</li>`
457
            ).join('')}
458
          </ul>
459
        </section>
460
      ` : ''}
461
      
462
      ${reflection.extendedBy?.length ? `
463
        <section>
464
          <h2>${i18n("theme_extended_by")}</h2>
465
          <ul>
466
            ${reflection.extendedBy.map(type => 
467
              `<li>${type.toString()}</li>`
468
            ).join('')}
469
          </ul>
470
        </section>
471
      ` : ''}
472
    </div>
473
  `;
474
}
475
```
476

477
### Plugin Internationalization
478

479
Support for internationalizing custom plugins and extensions.
480

481
```typescript { .api }
482
/**
483
 * Plugin with internationalization support
484
 */
485
abstract class InternationalizedPlugin extends AbstractComponent<Application, any> {
486
  /** Plugin translations */
487
  protected translations: Map<string, Partial<Record<string, string>>>;
488
  
489
  /**
490
   * Register plugin translations
491
   * @param locale - Locale code
492
   * @param translations - Plugin-specific translations
493
   */
494
  protected addPluginTranslations(locale: string, translations: Record<string, string>): void;
495
  
496
  /**
497
   * Get localized string for plugin
498
   * @param key - Translation key
499
   * @param args - Optional arguments
500
   * @returns Localized string
501
   */
502
  protected t(key: string, ...args: any[]): string;
503
}
504
```
505

506
**Usage Examples:**
507

508
```typescript
509
import { InternationalizedPlugin } from "typedoc";
510

511
class CustomPlugin extends InternationalizedPlugin {
512
  initialize() {
513
    // Add plugin-specific translations
514
    this.addPluginTranslations("en", {
515
      "custom_feature_title": "Custom Feature",
516
      "custom_feature_description": "This is a custom feature",
517
      "custom_error_message": "Custom error occurred",
518
    });
519
    
520
    this.addPluginTranslations("de", {
521
      "custom_feature_title": "Benutzerdefinierte Funktion",
522
      "custom_feature_description": "Dies ist eine benutzerdefinierte Funktion",
523
      "custom_error_message": "Benutzerdefinierter Fehler aufgetreten",
524
    });
525
    
526
    // Use translations in plugin logic
527
    this.listenTo(this.owner, "beginRender", () => {
528
      console.log(this.t("custom_feature_title"));
529
    });
530
  }
531
}
532
```
533

534
## Configuration Options
535

536
### Language Configuration
537

538
```typescript { .api }
539
/**
540
 * Language-related configuration options
541
 */
542
interface LanguageOptions {
543
  /** Primary locale for documentation */
544
  lang: string;
545
  /** Additional locales to generate */
546
  locales: string[];
547
  /** Custom translation directory */
548
  translationsDir?: string;
549
  /** Fallback locale for missing translations */
550
  fallbackLocale?: string;
551
}
552
```
553

554
**Usage Examples:**
555

556
```typescript
557
import { Application } from "typedoc";
558

559
// Multi-language documentation generation
560
const app = await Application.bootstrap({
561
  entryPoints: ["src/index.ts"],
562
  out: "docs",
563
  lang: "en",
564
  locales: ["en", "de", "ja", "zh"],
565
  translationsDir: "./custom-translations",
566
  fallbackLocale: "en",
567
});
568

569
// This will generate separate documentation for each locale
570
const project = await app.convert();
571
if (project) {
572
  for (const locale of ["en", "de", "ja", "zh"]) {
573
    app.internationalization.setLocale(locale);
574
    await app.generateDocs(project, `docs/${locale}`);
575
  }
576
}
577
```
578

579
## Error Handling
580

581
The internationalization system handles various error conditions:
582

583
- **Missing Translations**: Fallback to default locale, logging of missing keys
584
- **Invalid Locales**: Validation of locale codes, fallback behavior
585
- **File Loading**: Translation file reading errors, JSON parsing failures
586
- **Memory Management**: Large translation datasets, memory optimization
587
- **Plugin Conflicts**: Conflicting translation keys, namespace isolation
588

589
All internationalization errors are logged with context about the locale and translation key for debugging.