Skip to content

Guard against module-scope l10n.t in webviews (strings extracted but never localized) #864

Description

Problem

l10n.t() calls placed at module scope in webview code can never be localized.

src/webviews/index.tsx calls l10n.config({ contents: globalThis.l10n_bundle ?? {} }) inside render(), but
src/webviews/_integration/WebviewRegistry.ts statically imports every view component. Module bodies therefore
execute at bundle load — before the bundle is configured — so any module-scope l10n.t(...) captures the English
source string permanently.

This fails silently: the strings are still extracted into l10n/bundle.l10n.json, translations are produced,
and they are simply never applied at runtime.

Known occurrences

  • src/webviews/documentdb/localQuickStart/LocalQuickStart.tsx — ~20 constant maps, ~120 strings
    (STAGE_LABELS, DOCKER_GUIDANCE, DOCKER_FAILURE_LABELS, DOCKER_GUIDES, PLAN_ITEMS, …).
    Being fixed as part of PR DocumentDB Local with Quick Start helpers #798 review follow-up (finding M1, option A: render-time functions + useMemo).
  • src/webviews/documentdb/collectionView/components/resultsTab/DataViewPanelJSON.tsx
    monacoOptions.ariaLabel (pre-existing).

Proposed work

Add an automated guard so this cannot regress:

  • Option A — ESLint rule. A custom rule (or no-restricted-syntax targeting a CallExpression for l10n.t
    at Program body depth) scoped to src/webviews/**.
  • Option B — guard test. A Jest test that parses the webview sources and asserts no l10n.t call appears
    outside a function/component body.

Option A gives inline editor feedback; Option B needs no custom rule plumbing. Either is acceptable.

Expected impact

Enabling the guard will surface additional existing call sites beyond the two listed above, so this is expected to
require a sweep across the webview code rather than a single-file fix. That is why it is tracked separately from
PR #798.

Context

From the PR #798 code review — finding M1, deferred option D.
See docs/ai-and-plans/PRs/798-local-quickstart/code-review-2026-08-04.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions