@intlify/message-compiler
@intlify/message-compiler is the low-level parser and code generator behind Vue I18n's message format. It turns strings containing named placeholders, list placeholders, pipe-separated plurals, linked messages, and literal interpolation into either JavaScript function source or a compact AST for JIT evaluation. It is aimed at Vue I18n and localization-tool authors, not application teams looking for a ready-to-call translation function or a command-line program.
Use it as an implementation component when you are deliberately building Vue I18n-compatible tooling. Application code should stay at the vue-i18n or unplugin layer, where the runtime helpers, integration, and safer build-time compilation are already handled.
Use it if
- You are building Vue I18n tooling that must parse or precompile exactly the same message syntax as the runtime
- You need generated message-function source for build-time compilation, including Node-side source maps
- You need a JIT AST that @intlify/core-base can evaluate instead of generating JavaScript source
- You are writing diagnostics, an editor, or a linter that needs syntax errors with offsets, line and column locations, and numeric error codes
- You only want translations in a Vue application: install vue-i18n and usually @intlify/unplugin-vue-i18n, because this package does not provide locale selection, fallback, number or date formatting, or a ready runtime translator
- Your toolchain runs on Node 20 or older: version 11.4.8 declares Node.js 22 or later, which is a hard platform jump for CI images and older LTS deployments
- You need standard ICU MessageFormat: Vue I18n uses its own syntax, including pipe-separated plural cases and @: links, so FormatJS or messageformat is a better interoperability choice
- You plan to compile untrusted text at runtime with new Function or eval: baseCompile returns executable source, which creates code-injection review work and can fail under a Content Security Policy that blocks dynamic code
- You want a stable standalone compiler contract with full user docs: the package README is one sentence, generated functions require Intlify runtime-context helpers, and a 12.0.0 alpha line already exists beside the current 11.x release
Setup reality
Install the package only in tooling that already understands Vue I18n message functions. Version 11.4.8 requires Node.js 22 or later and depends on an exactly matched `@intlify/shared` version plus `source-map-js`; mixing independently pinned Intlify internals is an avoidable source of breakage. ESM, CommonJS, Node, and browser export paths exist, and TypeScript declarations are included. The main `baseCompile(source, options)` call does not return a translator. In normal mode it returns JavaScript source whose function expects a context object containing helpers such as `normalize`, `interpolate`, `named`, `list`, `plural`, `linked`, and `type`. Those helpers belong to the Intlify runtime contract, so evaluating the string alone is insufficient. Prefer build-time compilation through the official Vue I18n unplugin when building an app. Dynamic evaluation with `new Function` also conflicts with strict CSP and must never accept attacker-controlled messages. In JIT mode, `code` is deliberately empty and the returned AST is meant for the compatible Intlify runtime. `optimize` defaults to true; `minify` only changes the JIT AST and removes descriptive property names, which is useful for payload size but poor for custom AST consumers. Location tracking defaults to true and powers useful error ranges, but disabling it trims AST data. Passing `onError` changes errors from immediate throws into callbacks so compilation may continue with a damaged result; treat any collected error as a failed asset. Source maps require `sourceMap: true`, a useful filename, and the Node build. Finally, this compiler accepts Vue I18n syntax rather than ICU MessageFormat, so confirm the format before migrating message catalogs.
Patterns
Compile a named-interpolation messagecompile-message
import { baseCompile } from '@intlify/message-compiler';
const result = baseCompile('Hello, {name}!');
console.log(result.code);
console.log(result.ast);The code is function source, not a finished translator. It expects Intlify context helpers including named, interpolate, and normalize.
Generate compact arrow-function sourcegenerate-arrow-function
const { code } = baseCompile('Welcome, {name}', {
mode: 'arrow',
needIndent: false,
breakLineCode: ';',
});Arrow mode changes the emitted source shape. It does not remove the need for the runtime context passed as ctx.
Compile Vue I18n plural casescompile-plural-message
const { code, ast } = baseCompile(
'no apples | one apple | {count} apples'
);Pipe-separated cases are Vue I18n plural syntax, not ICU plural syntax. Selection is performed later by the runtime's plural helper.
Compile positional placeholderscompile-list-interpolation
const { code } = baseCompile('Hello, {0}! You have {1} tasks.');Numeric placeholders compile to calls to the list helper; named placeholders such as {count} compile to the named helper.
Compile linked keys and modifierscompile-linked-message
const plain = baseCompile('Read @:links.terms').code;
const lowered = baseCompile('Email @.lower:labels.support').code;Linked keys and modifiers are resolved by the runtime context. The compiler does not load a locale object or verify that the target key exists.
Represent syntax characters literallyescape-message-syntax
const atSign = baseCompile("Contact {'@'}support.example");
const pipe = baseCompile("Use {'|'} between choices");Vue I18n literal interpolation uses single-quoted content inside braces. Plain @ and | can otherwise begin linked or plural syntax.
Parse without generating function sourceparse-message-ast
import { createParser } from '@intlify/message-compiler';
const parser = createParser();
const ast = parser.parse('Hello, {name}!');
console.log(ast.type, ast.body);The AST includes source locations by default. NodeTypes is a const enum in TypeScript, so inspect the declared interfaces before persisting custom AST assumptions.
Collect structured syntax errorscollect-compile-errors
const errors = [];
const result = baseCompile('Hello, {', {
onError(error) {
errors.push({
code: error.code,
domain: error.domain,
location: error.location,
message: error.message,
});
},
});
if (errors.length) throw new Error(JSON.stringify(errors));Providing onError prevents the default immediate throw. Do not use the returned code or AST when any error was collected.
Remove source locations from the ASTdisable-locations
const { ast } = baseCompile('Hello, {name}!', {
jit: true,
location: false,
});Location-free ASTs are smaller but cannot support precise editor ranges or source-map mappings.
Produce an optimized JIT ASTbuild-jit-ast
const { ast, code } = baseCompile('Hello, {name}!', {
jit: true,
optimize: true,
});
console.assert(code === '');JIT mode intentionally returns an empty code string. The AST must be evaluated by a compatible Intlify runtime, not called directly.
Minify a JIT AST for shippingminify-jit-ast
const { ast } = baseCompile('Hello, {name}!', {
jit: true,
optimize: true,
minify: true,
});Minification renames and removes descriptive AST properties. Only enable it when the consumer understands Intlify's compact node representation.
Generate a Node-side source mapgenerate-source-map
const result = baseCompile('Hello, {name}!', {
filename: 'locales/en.json',
sourceMap: true,
location: true,
});
console.log(result.map);Source-map generation is implemented in the Node build and depends on location data. Browser-oriented builds can return no map.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| @messageformat/core | npm | You need a runtime compiler for standards-oriented ICU MessageFormat messages outside Vue I18n |
| @formatjs/icu-messageformat-parser | npm | You need an ICU MessageFormat AST for FormatJS tooling, linting, or extraction |
| intl-messageformat | npm | Your application needs to compile and format ICU messages directly with plural, select, date, and number support |