Localization (i18n)
The engine renders every user-facing message — validation errors, REST error bodies, MCP tool errors — from a message catalog, so the same failure reads correc…
The engine renders every user-facing message — validation errors, REST error bodies, MCP tool errors — from a message catalog, so the same failure reads correctly in the caller's language without changing any error code. Codes stay stable; only the text is localized.
Locales
14 locales ship in core/i18n:
en, zh, zh-Hant, ja, ko, es, fr, de, pt, ru, ar, hi, vi, id.
They come from a single as const map, so Locale and the list of supported locales are derived — no
second hardcoded list:
export const LOCALES = { EN: 'en', ZH: 'zh', /* … */ } as const;
export type Locale = typeof LOCALES[keyof typeof LOCALES];
export const DEFAULT_LOCALE: Locale = LOCALES.EN;Message keys
MessageKey is the union of every key in the English catalog (core/i18n/en.ts), and each catalog is
typed Record<MessageKey, string>. That makes a missing translation a compile error in every
locale, not a runtime fallback.
export const en = {
'auth.missingKey': 'missing API key',
'rbac.denied.read': 'not allowed to read {object}',
// …
};translate(code, params, locale) interpolates {name} placeholders. Unknown placeholders without a
matching param are left literal (so a value like {seq} survives), and a missing locale or key
falls back to English.
Errors carry the locale
SchemaError(code, params, locale) stores the code, params and locale, and renders message up
front. Because the code and params are kept, a caller can re-render the same error later:
import { SchemaError } from '@weave-kit/engine';
throw new SchemaError('rbac.denied.read', { object: 'lead' }, locale);
// later, in another locale:
error.localize('fr');The REST layer maps any thrown SchemaError to a uniform { error: { code, message, params } } body
(error contract) and renders the message in the engine's configured locale — the
JSON/API boundary stays i18n-aware while adapters and clients only branch on code.
Configure
export default {
locale: 'en', // default; one of the LOCALES values
};Add a locale
- Create
core/i18n/<tag>.tsexporting a catalog typedRecord<MessageKey, string>(copyen.tsand translate). - Register it in the
LOCALESmap and thecatalogByTaglookup incore/i18n/index.ts.
Because catalogs are key-complete by type, the build fails until every key is translated.