WeaveKit Docs
GuidesPlatform

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

  1. Create core/i18n/<tag>.ts exporting a catalog typed Record<MessageKey, string> (copy en.ts and translate).
  2. Register it in the LOCALES map and the catalogByTag lookup in core/i18n/index.ts.

Because catalogs are key-complete by type, the build fails until every key is translated.

On this page