Localization strategy for shell completions and internal packages with static English strings

[tnaum-ms]

Problem

Several internal packages and modules contain hardcoded English strings that are user-facing but cannot be easily localized with the current vscode.l10n.t() / @vscode/l10n approach:

1. Shell Completion Provider (ShellCompletionProvider.ts)

Completion candidate detail strings (e.g., 'Show databases or collections', 'Switch to a database') and method descriptions from getMethodsByTarget() are hardcoded English. These display in the terminal completion picker.

Challenge: The shell completion module is platform-neutral and doesn't import vscode.l10n. The strings come from method registries that are static data, not call-site strings. The l10n tooling (npm run l10n) extracts strings from l10n.t() calls to build the bundle — if strings are defined in a registry/constant file without l10n.t(), they won't be extracted.

2. documentdb-constants package

Contains help text, operator descriptions, and documentation strings embedded as static data. These are consumed across multiple surfaces (Collection View, Playground, Shell) but are hardcoded English.

3. documentdb-shell-api-types package

Method descriptions in the method registry are English-only.

The Core Challenge

The l10n bundle generation (npm run l10n) works by statically extracting l10n.t('...') call sites. For data that's defined as constants/registries:

• Wrapping each constant in l10n.t() at definition site might work but needs verification that the extraction tooling handles it
• Alternatively, localization could happen at the consumption site, but that requires knowing all the possible strings ahead of time
• For packages consumed via workspace references, the l10n bundle is the extension's bundle.l10n.json — package-level l10n bundles aren't a thing yet

Possible Approaches

1. Wrap static strings at definition in l10n.t() — verify extraction works for @vscode/l10n in packages
2. Create a mapping layer at the extension boundary that localizes known strings from packages
3. Accept English-only for terminal/shell output (shell convention) but localize picker/completion UI
4. Defer to a future l10n infrastructure that supports package-level bundles

Decision Needed

Which strings are considered "user-facing" per project rules:

• Terminal completion details in the picker UI?
• Shell help text output?
• Operator/function documentation in hover tooltips?

References

• PR Features from release 0.8.0  #573 review issue H2
• src/documentdb/shell/ShellCompletionProvider.ts
• packages/documentdb-constants/
• packages/documentdb-shell-api-types/src/methodRegistry.ts