Skip to content

fix(theme): make i18n strings extractable by write-translations#1499

Open
navrocky wants to merge 1 commit into
PaloAltoNetworks:mainfrom
navrocky:fix/i18n
Open

fix(theme): make i18n strings extractable by write-translations#1499
navrocky wants to merge 1 commit into
PaloAltoNetworks:mainfrom
navrocky:fix/i18n

Conversation

@navrocky

@navrocky navrocky commented Jun 9, 2026

Copy link
Copy Markdown

Description

Every UI string in the theme was wrapped with translate() / <Translate>, but the id was referenced through constants imported from translationIds.ts. Docusaurus' write-translations only performs static analysis (@docusaurus/babel): it evaluates each call's argument with Babel's path.evaluate() and keeps it only when the result is confident. An id read from an imported constant is a cross-module member expression that Babel cannot statically resolve, so every call was skipped (with a warning) and nothing was written to the locale code.json. Consuming projects therefore got an empty translation template even though the English defaults rendered fine at runtime.

Changes:

  • Inline all translation ids as string literals at the call site — the approach Docusaurus theme-classic uses and its i18n guide mandates ("Text labels must be static"): https://docusaurus.io/docs/i18n/tutorial#translate-your-react-code
  • Remove the translationIds.ts dictionary; keep an explanatory note in its place so the removal is discoverable and the pattern isn't reintroduced.
  • Wrap strings that were not localized at all: Authorization (SecuritySchemes), Export / OpenAPI Spec (Export), Add item (ParamArrayFormItem).
  • Replace the dynamic translate({ id: someVar }) in SecuritySchemes.renderRest with static per-key calls so description/scheme/bearerFormat/openIdConnectUrl are extracted too.

write-translations now statically extracts all theme.openapi.* ids.

Part of #319
Improve of #1210

Every UI string in the theme was wrapped with `translate()` / `<Translate>`,
but the `id` was referenced through constants imported from `translationIds.ts`.
Docusaurus' `write-translations` only performs static analysis (@docusaurus/babel):
it evaluates each call's argument with Babel's `path.evaluate()` and keeps it only
when the result is `confident`. An id read from an imported constant is a
cross-module member expression that Babel cannot statically resolve, so every call
was skipped (with a warning) and nothing was written to the locale `code.json`.
Consuming projects therefore got an empty translation template even though the
English defaults rendered fine at runtime.

Changes:
- Inline all translation ids as string literals at the call site — the approach
  Docusaurus theme-classic uses and its i18n guide mandates ("Text labels must be
  static"): https://docusaurus.io/docs/i18n/tutorial#translate-your-react-code
- Remove the `translationIds.ts` dictionary; keep an explanatory note in its place
  so the removal is discoverable and the pattern isn't reintroduced.
- Wrap strings that were not localized at all: Authorization (SecuritySchemes),
  Export / OpenAPI Spec (Export), Add item (ParamArrayFormItem).
- Replace the dynamic `translate({ id: someVar })` in SecuritySchemes.renderRest
  with static per-key calls so description/scheme/bearerFormat/openIdConnectUrl
  are extracted too.

`write-translations` now statically extracts all `theme.openapi.*` ids.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant