Skip to main content

translations

Install translation lookup with registerTranslations() and use the accessor returned by core.register().

The standalone i18n package provides your addon's typed translation verbs and locale resolution independently of Runtime integration. Install this reader to resolve strings from other addons.

Import​

import { core } from '@bedrock-core/server';
import { registerTranslations, translations } from '@bedrock-core/server-runtime/i18n';
import type { Translations } from '@bedrock-core/server-runtime/i18n';

Signature​

translations(runtime: Runtime): Translations

Parameters​

ParameterTypeDefaultDescription
runtimeRuntime—Registered runtime with registerTranslations() installed

Returns​

The installed Translations registry. Calling translations(runtime) without installing registerTranslations() throws.

Usage​

import manifest from '../manifest.json';
import '../i18n';

const addon = core.register({
manifest,
translations: registerTranslations(),
});

const language = addon.translations;
const resolve = language.forLocale('en_US');

Import your shared i18n instance during startup so its default bundle is available for automatic publication.

Use addon.translations directly after registration. In another module, translations(core) retrieves that same installed reader:

const language = translations(core);

Installation opens the reader; lookups read its current snapshot. Initial remote reads can return undefined until snapshots arrive. Subscribe to bundles when dependent state needs to follow availability or updates.

Publishing​

Runtime checks the default i18n instance on the first scheduled tick after registration and publishes its bundle if available. This happens independently of reader installation. An explicit publication made before that check takes precedence.

An addon sharing only its default bundle can register with core.register({ manifest }). For an explicit publication or replacement, use the publisher entry:

import { core } from '@bedrock-core/server';
import { publishTranslations } from '@bedrock-core/server-runtime/i18n/publish';
import manifest from '../manifest.json';
import { i18n } from '../i18n';

core.register({ manifest });
publishTranslations(core, i18n.bundle);

For an installed reader, language.provide(bundle) performs the same local publication update; language.own() reads that publication. Publish replacements explicitly with provide or publishTranslations after the initial automatic check.

Bundles​

Each record is an I18nBundle keyed by the publishing addon's namespace. Publications and replacements are broadcast through core:translations; only installed readers retain foreign translation bundles. A reader requests initial snapshots from compatible providers and validates received snapshots before exposing their records. Template strings retain their placeholders and recorded argument order.

language.bundles: ReadonlyObservable<Readonly<Record<string, I18nBundle>>>

get() returns the current available bundles. Subscriptions receive (next, previous) and do not replay the current value. Snapshots and broadcast updates arrive asynchronously. Withdrawal and provider departure remove the corresponding live data.

Removing the reader releases its retained foreign bundles while the local publication continues. Runtime shutdown stops the reader and withdraws its local publication.

Resolvers​

language.of(addonId: string): I18nBundle | undefined
language.i18n(addonId: string): I18n<unknown> | undefined
language.forLocale(locale: string): TranslationResolver
language.forPlayer(player: Player, defaultLocale = 'en_US'): TranslationResolver

i18n returns verbs over the current bundle. Observe bundles and obtain a fresh view after replacement. Locale resolvers retain their identity and read the current bundle chain on each call.

A TranslationResolver is (key: string) => string | undefined. Pass a complete language key; an unavailable key returns undefined.

import type { Player } from '@minecraft/server';

function shopTitle(player: Player): string {
const resolve = language.forPlayer(player);
return resolve('studio_shop.shop.title') ?? 'Shop';
}

Player resolution uses the persisted locale override, client locale, sibling language region, default locale and available bundle locales. An invalid player handle uses the default locale.

The library owns locale fallback and bundle selection. Registry transport supplies current compatible data; it does not change native manifest fields or resource-pack language keys.