Skip to main content

Localizing a guide

A guide is translated by writing the same tree under another locale folder, and the guides stage turns every locale into .lang entries, so the client resolves guide prose in each player's own language.

The default locale is the structure​

The default locale is the single source of structural truth. It defines the page set, the key set, the sidebar and the prev/next chain; other locales contribute values only.

Translators edit the per-locale MDX, never the .lang. The generated section is fully regenerated on every build, so editing a page reshuffles the key indices harmlessly.

Every locale's generated section contains the complete default-locale key set. Untranslated keys are filled with default-locale values, and drift between locales is reported; the stage's strictLocales setting makes it fatal.

Keys​

Every title, heading, and paragraph or list item without links becomes a localization key. Keys are structural, never content-derived: the same deterministic walk runs over every locale, so identical document structure pairs keys positionally.

<ns>.guides.<page_path>.<node_path> page content
<ns>.guides._cat.<dir_path> category labels

Node paths are title, b<N> (top-level block), b<N>.b<M> (admonition child), b<N>.t (admonition custom title), and b<N>.i<M>[.i<P>…] (list item). <ns> is the addon namespace, the same prefix every other key the pack emits sits under.

A paragraph or list item with internal links has no key. The manifest carries it as a tagged string in every locale — See <0>the page</0>. — and the pages its numbered tags open, and the ui-compiler breaks it into lines per locale and draws it through keys of its own.

A tag's number is its page's place among the default locale's links, so a translation may reorder them. A locale that did not translate the paragraph gets the default locale's text.

Admonition titles​

Admonition default titles (Note, Tip, …) are not the stage's output. They are @bedrock-core/guides' own typed i18n resources under core.guides.adm.*, folded into your bundle by library discovery — override them there.

The .lang section​

The stage appends its entries to RP/texts/<locale>.lang and updates RP/texts/languages.json. The i18n stage writes into the same files, each stage inside its own marker-delimited section and each rewriting only its own:

## <core:generated-guides:begin:gameplay> generated by @bedrock-core
creator_pack.guides.intro.title=Welcome
## <core:generated-guides:end:gameplay>

Re-running is idempotent, and hand-written entries outside the markers are preserved. The i18n stage reads whatever it did not write as extra passthrough, so guide prose is measurable by the layout engine — which is why guides runs before i18n.

Next steps​

  • Authoring a guide — pages, categories and blocks
  • i18n — the localization system the .lang entries join
  • guides stage — defaultLocale, strictLocales and the other settings