i18n
@bedrock-core/i18n is the localization layer for Minecraft Bedrock addons: typed keys, typed interpolation and plurals, resolved on the client in each player's own language wherever possible, and on the server whenever your code needs the actual string.
@bedrock-core/i18n is in beta: the API can change between releases. Pin exact versions and read the changelog before upgrading.
What is @bedrock-core/i18n?
The runtime creates typed translation verbs directly from locale objects or a prepared bundle. The optional i18n Builder stage generates client .lang files, compiles locale data and supplies the owning namespace plus library/vanilla resource declarations.
The conventions are i18next's — {{var}} interpolation, _one/_other plural suffixes, the selector call shape — so existing knowledge transfers. The implementation uses its own locale data and interpolation helpers.
Install
Add the standalone package to the addon or library that uses it:
- npm
- yarn
- pnpm
npm install @bedrock-core/i18n
yarn add @bedrock-core/i18n
pnpm add @bedrock-core/i18n
import { createI18n } from '@bedrock-core/i18n';
Setup
Create the shared instance in the owning pack's i18n/index.ts:
// packs/BP/i18n/index.ts
import { createI18n } from '@bedrock-core/i18n';
import en_US from './en_US';
import es_ES from './es_ES';
export const i18n = createI18n({ en_US, es_ES });
Key paths, interpolation variables and plural forms are inferred from the locale objects. Builder reads this entry, compiles client and server translations, and binds the owning manifest's namespace.
Outside Builder, provide the namespace explicitly:
import { createI18n } from '@bedrock-core/i18n';
const i18n = createI18n({
en_US: { shop: { title: 'Shop' } },
es_ES: { shop: { title: 'Tienda' } },
}, { namespace: 'studio_shop' });
const title = i18n.forLocale('en_US').t($ => $.shop.title);
Server-side lookup needs no compilation. Client-facing key() and raw() calls still require matching language entries in the resource pack; Builder generates those entries from the same locale objects.
createI18n also registers this instance as the addon's default translation source, which is what lets Text measure localized children with no further wiring.
What you get
- Client-first resolution.
key()andraw()defer to the client, so each player sees their own language at no per-player cost on the server;t()resolves now, server-side, for whichever locale you're bound to. See The three verbs. - Typed everything. Key paths, required interpolation variables and plural forms all come from the bundle's inferred type — an unknown path or a missing argument is a compile error, not a blank string in game.
- Plurals without
Intl. A built-in CLDR rule table picks_one/_few/_otherper locale, since Bedrock's script engine has noIntl.PluralRules. - One
DisplayTextchannel.Textchildren,HeaderandMenuRowlabels, and registry display fields all accept the samestring | RawMessageunion, resolved lazily by whichever resolver is active. - Cross-addon sharing. Core publishes an available default bundle independently of optional readers. Install
registerTranslations()to read compatible foreign bundles and create shared resolvers; publisher-only updates usepublishTranslations— see Cross-addon sharing.
Next steps
- Authoring resources — locale files, namespacing, interpolation, plurals and pack display text
- Libraries and overrides — folding a dependency's strings into your bundle, overriding library and vanilla strings
- API reference — the three verbs, locale resolution,
createI18nand every export - i18n builder stage — generating
.langfiles and the runtime bundle from your resources - useTranslation — binding the typed verbs to the viewing player inside a component
- TranslationContext — overriding which resolver a subtree sees