Skip to main content

Localizing a guide

A guide is translated by writing the same tree under another locale folder, and the guides filter 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 filter'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 filter'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 filter appends its entries to RP/texts/<locale>.lang and updates RP/texts/languages.json. The i18n filter writes into the same files, each filter inside its own marker-delimited section and each rewriting only its own:

## <core:generated-guides:begin> do not edit — generated by the guides regolith filter
creator_pack.guides.intro.title=Welcome
## <core:generated-guides:end>

Re-running is idempotent, and hand-written entries outside the markers are preserved. The i18n filter 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 filter — defaultLocale, strictLocales and the other settings
On this page