LCX/LCL Localization Files and Build Integration

Relevant source files

• .c8rc.json
• .dprint.jsonc
• .github/codecov.yml
• .github/codeql/codeql-configuration.yml
• .vscode/extensions.json
• .vscode/launch.template.json
• .vscode/settings.template.json
• .vscode/tasks.json
• Herebyfile.mjs
• azure-pipelines.release.yml
• eslint.config.mjs
• knip.jsonc
• package-lock.json
• package.json
• scripts/addPackageJsonGitHead.mjs
• scripts/browserIntegrationTest.mjs
• scripts/build/options.mjs
• scripts/build/tests.mjs
• scripts/build/utils.mjs
• scripts/configurePrerelease.mjs
• scripts/dtsBundler.mjs
• scripts/eslint/rules/argument-trivia.cjs
• scripts/eslint/rules/debug-assert.cjs
• scripts/eslint/rules/js-extensions.cjs
• scripts/eslint/rules/jsdoc-format.cjs
• scripts/eslint/rules/no-in-operator.cjs
• scripts/eslint/rules/no-keywords.cjs
• scripts/eslint/rules/only-arrow-functions.cjs
• scripts/generateLocalizedDiagnosticMessages.mjs
• scripts/post-vsts-artifact-comment.mjs
• scripts/processDiagnosticMessages.mjs
• scripts/produceLKG.mjs
• scripts/regenerate-unicode-identifier-parts.mjs
• src/compiler/corePublic.ts
• src/loc/lcl/chs/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/cht/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/csy/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/deu/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/esn/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/fra/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/ita/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/jpn/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/kor/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/plk/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/ptb/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/rus/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/loc/lcl/trk/diagnosticMessages/diagnosticMessages.generated.json.lcl
• src/testRunner/_namespaces/ts.server.ts
• src/testRunner/_namespaces/ts.ts
• src/testRunner/unittests/sys/symlinkWatching.ts
• src/testRunner/unittests/tsserver/findAllReferences.ts
• src/testRunner/unittests/tsserver/goToDefinition.ts
• src/tsc/_namespaces/ts.ts
• src/tsc/tsconfig.json
• src/tsconfig.json
• src/tsserver/tsconfig.json
• src/typingsInstaller/tsconfig.json
• src/watchGuard/tsconfig.json

TypeScript diagnostic messages are localized into 13 languages (including Chinese, Japanese, German, Spanish, and others) using the Microsoft Localization Studio (LCX/LCL) format. This system ensures that developers using the compiler (tsc) or the language server (tsserver) receive error messages and CLI help in their configured system language.

Overview of Localization Artifacts

The localization process involves three primary file types:

1. diagnosticMessages.json: The source of truth for all diagnostic messages in English.
2. src/loc/lcl/<lang>/*.lcl: Localization Library files containing the translated strings for a specific language.
3. Generated JSON: The build system merges these to produce language-specific artifacts used at runtime.

The LCL File Structure

LCL files are XML-based documents that map English message keys (derived from the original message text and ID) to their translated counterparts.

Component	Description
ItemId	A unique identifier combining the message name and its numeric code (e.g., ;ALL_COMPILER_OPTIONS_6917) src/loc/lcl/chs/diagnosticMessages/diagnosticMessages.generated.json.lcl24
Val (Source)	The original English text, often containing placeholders like {0} src/loc/lcl/chs/diagnosticMessages/diagnosticMessages.generated.json.lcl35
Tgt (Target)	The translated text for the specific locale src/loc/lcl/chs/diagnosticMessages/diagnosticMessages.generated.json.lcl37

Data Flow: Natural Language to Code Entity

The following diagram illustrates how a natural language error message authored by a developer is transformed into a localized code entity within the TypeScript build artifacts.

Diagnostic Translation Pipeline

Sources: src/loc/lcl/chs/diagnosticMessages/diagnosticMessages.generated.json.lcl24-41 scripts/generateLocalizedDiagnosticMessages.mjs1-20

Build Integration

The localization process is integrated into the main build pipeline managed by hereby. The build system orchestrates the generation of localized diagnostic maps that the compiler loads at runtime.

Key Build Scripts

• scripts/processDiagnosticMessages.mjs: Processes the base English messages and generates the initial ID mappings.
• scripts/generateLocalizedDiagnosticMessages.mjs: Parsers the LCL files and produces the localized output files found in the lib/ directory (e.g., lib/zh-cn/diagnosticMessages.generated.json).

Localization Build Flow

The build system ensures that whenever diagnosticMessages.json is updated, the corresponding localized versions are synchronized.

Build Artifact Generation

Sources: Herebyfile.mjs1-50 scripts/processDiagnosticMessages.mjs1-10 scripts/generateLocalizedDiagnosticMessages.mjs1-15

Supported Locales

TypeScript maintains translations for the following directory structures under src/loc/lcl/:

Directory	Language	Source Example
chs	Chinese (Simplified)	src/loc/lcl/chs/diagnosticMessages/diagnosticMessages.generated.json.lcl2
cht	Chinese (Traditional)	src/loc/lcl/cht/diagnosticMessages/diagnosticMessages.generated.json.lcl2
deu	German	src/loc/lcl/deu/diagnosticMessages/diagnosticMessages.generated.json.lcl2
esn	Spanish	src/loc/lcl/esn/diagnosticMessages/diagnosticMessages.generated.json.lcl2
fra	French	src/loc/lcl/fra/diagnosticMessages/diagnosticMessages.generated.json.lcl2
ita	Italian	src/loc/lcl/ita/diagnosticMessages/diagnosticMessages.generated.json.lcl2
jpn	Japanese	src/loc/lcl/jpn/diagnosticMessages/diagnosticMessages.generated.json.lcl2
kor	Korean	src/loc/lcl/kor/diagnosticMessages/diagnosticMessages.generated.json.lcl2
plk	Polish	src/loc/lcl/plk/diagnosticMessages/diagnosticMessages.generated.json.lcl2
ptb	Portuguese (Brazil)	src/loc/lcl/ptb/diagnosticMessages/diagnosticMessages.generated.json.lcl2
rus	Russian	src/loc/lcl/rus/diagnosticMessages/diagnosticMessages.generated.json.lcl2
trk	Turkish	src/loc/lcl/trk/diagnosticMessages/diagnosticMessages.generated.json.lcl2

Runtime Resolution

When the compiler or language service needs to report a diagnostic, it uses the ts.Diagnostics object. If a localized bundle is available for the current environment's locale, the compiler's internal getLocaleSpecificMessage function (or equivalent logic in the host) replaces the default English string with the value extracted from the generated JSON derived from the LCL files.

Sources: src/compiler/corePublic.ts1-100 src/loc/lcl/chs/diagnosticMessages/diagnosticMessages.generated.json.lcl1-30