Skip to main content

Localization Architecture

The Docusaurus user docs site (docs.rat.gd) serves user-facing docs in the browser's locale, reading translated files from website/i18n/.

Supported locales​

Defined in website/docusaurus.config.ts:

en  ca  de  es  eu  fr  gl  it  nl  pt

en is the default. The dev docs site (docusaurus.dev.config.ts) is English-only.

File layout​

website/i18n/
└── {locale}/                          (one folder per non-English locale)
    ├── code.json                       ← Docusaurus chrome strings (generated stubs)
    ├── docusaurus-plugin-content-docs/
    │   ├── current.json               ← sidebar category labels
    │   └── current/
    │       └── legal/
    │           ├── about.md           ← translated legal page content
    │           ├── terms.md
    │           └── privacy.md
    └── docusaurus-theme-classic/
        ├── navbar.json                ← navbar item labels
        └── footer.json                ← footer link labels and copyright

docs/user/legal/
├── about.md                           ← English canonical
├── terms.md
├── privacy.md
└── licenses.md                        ← generated by `npm run license:doc`

licenses.md is not translated — it lists package names and SPDX identifiers which have no meaningful locale-specific form.

File types​

code.json​

Generated stubs for miscellaneous Docusaurus chrome strings not covered by the other files. Created by:

cd website && npx docusaurus write-translations --locale {locale}

Strings not translated in this file fall back to their English default automatically.

docusaurus-theme-classic/navbar.json and footer.json​

Translate navbar item labels and footer link labels / copyright text. Also generated by write-translations as stubs; fill in "message" values for each key.

docusaurus-plugin-content-docs/current.json​

Sidebar category labels (e.g. "Getting Started", "Features"). Generated stubs; leave untranslated if the sidebar is English-only.

docusaurus-plugin-content-docs/current/legal/*.md​

The actual translated content for each legal page. Mirror the filename from docs/user/legal/. Must include the same frontmatter as the English canonical (id, title, unlisted: true).

Fallback behaviour​

Docusaurus falls back per-file: if a translated .md does not exist for a locale, the English canonical is shown at that locale's URL. This means you can translate only legal/ without touching the rest of the docs — untranslated pages are served in English rather than 404-ing.

Current state (2026-07-19): only legal/ is translated. The user guides (activity-templates.md, gforms-user-guide.md, new-user-flow.md, org-import-export.md, mobile-access.md) are deliberately English-only — their translation has not started. New user guides should be written in English only; the fallback above serves them at every locale's URL.

Dev docs site​

docusaurus.dev.config.ts sets i18n: { defaultLocale: "en", locales: ["en"] }. The dev docs are English-only and have no i18n files. Translated legal pages do not appear there — the dev site serves the English canonical directly from docs/user/legal/.

How to add a new locale​

  1. Add the locale code to i18n.locales in website/docusaurus.config.ts.
  2. Run write-translations to generate stubs: 
    cd website && npx docusaurus write-translations --locale {locale}
    This creates website/i18n/{locale}/code.json, navbar.json, footer.json, and current.json.
  3. Translate footer.json (footer link labels and copyright) and navbar.json if needed.
  4. Create translated legal docs: 
    website/i18n/{locale}/docusaurus-plugin-content-docs/current/legal/about.md
    website/i18n/{locale}/docusaurus-plugin-content-docs/current/legal/terms.md
    website/i18n/{locale}/docusaurus-plugin-content-docs/current/legal/privacy.md
    Each file must include unlisted: true in frontmatter.
  5. Verify: cd website && npm run build — check for broken-link warnings.

Content authoring rules for shared Markdown​

Files in docs/user/legal/ are rendered by Docusaurus. Use plain CommonMark/GFM and raw HTML only — Docusaurus admonitions and MDX components are safe on the docs site but avoid them if the content may be consumed elsewhere.

Search engine visibility​

All legal pages carry unlisted: true in frontmatter. This:

  • Adds a noindex meta tag via Docusaurus's UnlistedMetadata component.
  • Hides the page from the Docusaurus sidebar.
  • Excludes the page from the Docusaurus sitemap (the sitemap plugin respects noindex).

The visual "Unlisted page" warning banner is suppressed by website/src/css/custom.css:

.theme-unlisted-banner { display: none; }

website/static/robots.txt provides an additional crawl-level signal:

User-agent: *
Disallow: /docs/legal/
Disallow: /legal/