Skip to main content

Authoring resources

Nested TypeScript objects under packs/BP/i18n/ are the source of truth for an addon's text. The i18n builder stage reads them and generates the .lang files, the runtime bundle and the types.

Locale files​

Pass locale objects directly to createI18n in i18n/index.ts, or import them from separate files. A separate locale module default-exports its nested object:

// packs/BP/i18n/en_US.ts
export default {
shop: {
title: 'Shop',
bought: 'You bought {{item}} for {{price}} emeralds.',
stock_one: '{{count}} left in stock',
stock_other: '{{count}} left in stock',
},
} as const;

Use as const on separately exported locale objects to retain literal templates and their interpolation variables. Inline objects passed to createI18n retain literal types through its const-generic signature.

The default locale (defaultLocale, en_US unless configured) defines the key shape and interpolation arguments. Strict mode rejects missing or extra keys and variable drift. With strict: false, missing keys use default-locale values and extra keys are dropped with warnings.

Separate locale files use <xx_YY>.ts, .js, .mts or .mjs. Locale names are checked against the supported client catalog. Declaration files are ignored. Keep the shared runtime instance in i18n/index.ts alongside the locale files. Builder reads the locale map passed to createI18n; other files in that folder are not treated as locale names.

Export one shared createI18n instance from the canonical index, named or default. Import the factory from @bedrock-core/i18n; import aliases and namespace imports are supported. Builder supplies the owning manifest namespace. An explicitly supplied namespace must match it.

Keys are constrained by what has to survive as both a .lang key segment and a TypeScript property:

RuleWhy
Segments match [A-Za-z0-9_]+must survive a key=value line and a TS property name
Values are single-line stringsa .lang entry is one line
Nesting depth ≤ 6past that, type-level path recursion degrades the whole key union to string
Leaves are strings, branches are objectsarrays and other types are rejected

Namespacing​

Every key lands in the .lang files prefixed with the addon's namespace: shop.bought becomes drav0011_shop.shop.bought. The prefix is what keeps addons from colliding everywhere their text meets — Bedrock merges every installed pack's .lang into one world-wide table, and the server runtime merges every addon's published translation tables under the same namespace.

Builder takes the namespace from the owning authored manifest:

manifest.json (fragment)
{ "namespace": "drav0011_shop" }

When using the server framework, use the owning manifest's explicit namespace, matching runtime registration. The generated bundle carries this namespace; standalone compileI18n callers supply it explicitly.

Call sites never spell the namespace. key() and raw() prepend it at runtime from the bundle's metadata, so renaming the addon's namespace never touches a call site.

Argument order​

{{var}} syntax is rewritten to Minecraft's positional form for the .lang files:

'You bought {{item}} for {{price}}' -> 'You bought %1$s for %2$s'

The placeholders are numbered by first appearance in the default locale. Because every locale's .lang uses those same numbers, a translation may put the arguments in any order its sentence needs and each still lands in the right place — reordering the words never reorders the values. The runtime bundle keeps the original {{var}} template and substitutes by name, so script-side text (t(), raw()) is unaffected by argument order either way.

Nesting with $t()​

$t(other.key) references are inlined at build time, recursively — Bedrock .lang has no nesting:

demo: {
title: 'i18n Demo',
intro: 'Every verb the library has, live: $t(demo.title).',
},

Strict mode rejects unknown references and cycles. With strict: false, they produce warnings and empty strings.

Format functions are not supported

{{price, currency}} does not work. A format function is JavaScript and cannot travel to the client. Format in code, pass the result as the argument.

Tags for <Trans>​

A string drawn with <Trans> marks its links and styles with named tags, which the screen maps to components:

help: { prices: 'See <shop>the shop</shop> for <gold>today</gold>\'s prices.' },

The tags pass through this stage untouched. A translation may move them, reorder them and wrap them around other words. The string is composed at build, so it cannot also take {{variables}}.

Plurals​

Author _one / _other variants (plus _zero, _two, _few, _many where a language needs them). A plural group with no _other fails the build — it is the universal fallback category, and a group without it resolves to nothing for most counts.

CLDR categories differ per language, so a locale may declare a category the default locale never has. Czech needs _few; English does not:

// packs/BP/i18n/en_US.ts // packs/BP/i18n/cs_CZ.ts
stock_one: '{{count}} left', stock_one: 'Zbývá {{count}} kus',
stock_other: '{{count}} left', stock_few: 'Zbývají {{count}} kusy',
stock_other: 'Zbývá {{count}} kusů',

cs_CZ.stock_few is not flagged as an extra key: it rides into the bundle, checks its variables against the group's _other, and picks up its recorded argument order from the locale that defines it. What parity still requires is that the default locale declares the group (stock_other). See Plurals for how a plural leaf resolves at runtime.

Pack display text​

Use a pack branch for the name and description shown in the pack list:

export default {
pack: {
name: 'Shop',
description: 'Sells items to players',
creator: 'DrAv0011',
},
shop: { title: 'Shop' },
} as const;

These fields use the same names as vanilla manifests. Builder writes their values to the owning pack's language files when its manifest references the literal keys:

packs/BP/manifest.json and packs/RP/manifest.json
{
"header": {
"name": "pack.name",
"description": "pack.description"
}
}

A linked resource pack inherits these display translations when it has one behavior-pack owner and no locale modules of its own. A shared resource pack, or one with its own locale modules, keeps its own display metadata.

config.json supplies display defaults. Locale pack values override those defaults; pack-specific texts/<locale>.lang aliases take precedence when they differ from the project defaults. Each generated display key is emitted once. The manifest stage also registers en_US in texts/languages.json for fallback display text, including builds without the i18n stage.

The resource pack receives namespaced translations such as <namespace>.pack.name alongside the manifest aliases it owns. The behavior pack receives its manifest aliases; authored language entries are preserved. pack.creator remains a namespaced translation with no manifest alias.

Next steps​

  • API — Translate keys and format arguments at runtime