|
| 1 | +# Localization |
| 2 | + |
| 3 | +English is the source language. Simplified Chinese (`zh-cn`) is the first |
| 4 | +translation. The pack follows VS Code's display language and normal reload |
| 5 | +behavior, with English fallback. There is no separate language setting. |
| 6 | + |
| 7 | +## Manifest resources |
| 8 | + |
| 9 | +Pack-owned manifest UI text uses semantic `%key%` references in `package.json`. |
| 10 | +Keep English defaults in `package.nls.json` and translate every key in |
| 11 | +`package.nls.<locale>.json`. This includes the walkthrough, media alternative |
| 12 | +text, command and shortcut captions, settings descriptions and formatter editor |
| 13 | +name. Keep the existing English wording when externalizing text. |
| 14 | + |
| 15 | +Use VS Code locale names (for example `zh-cn`, not `zh_CN`). Preserve product |
| 16 | +names, codicons, Markdown structure, link targets and encoded command arguments. |
| 17 | +Never translate command IDs, settings keys, enum values, paths or telemetry |
| 18 | +identifiers. The pack does not translate its bundled extensions. |
| 19 | + |
| 20 | +## Native messages and webviews |
| 21 | + |
| 22 | +The manifest's `l10n: "./l10n"` lets VS Code select the runtime bundle. |
| 23 | +Extension-host code uses `vscode.l10n.t("Complete message {0}", value)`. |
| 24 | +Do not dynamically translate exception messages or assemble sentences from |
| 25 | +translated fragments. Retain original errors in logs and localize the |
| 26 | +pack-authored explanation. Dialog actions use message-item object identity, |
| 27 | +not comparisons against English or translated captions; cancellation remains |
| 28 | +`undefined`. |
| 29 | + |
| 30 | +All eight webviews are localized: Overview, Help Center, Tips for Beginners, |
| 31 | +Extensions Guide, Install JDK, Java Runtime, Project Settings and Formatter |
| 32 | +Settings. The legacy Java Runtime page remains supported by its serializer; |
| 33 | +the current `java.runtime` command opens Project Settings' JDK page. |
| 34 | + |
| 35 | +Use `src/l10n/host.ts` for native HTML titles, language attributes, escaping and |
| 36 | +the nonce-protected inert JSON bootstrap. Pass only the active |
| 37 | +`vscode.l10n.bundle` and `vscode.env.language`; do not discover catalogs, |
| 38 | +inspect `navigator.language`, fetch translations, change CSP or expand |
| 39 | +`localResourceRoots`. Browser entries import `src/l10n/browser.ts` before |
| 40 | +rendering and use `@vscode/l10n`, never `vscode`. Missing bundles or keys use |
| 41 | +English; malformed bootstraps are explicit errors. Restored panels rebuild |
| 42 | +their titles and bootstrap using the current language. |
| 43 | + |
| 44 | +Call translation functions lazily at presentation boundaries, not in |
| 45 | +module-level metadata before initialization. Keep raw `ProjectType`, |
| 46 | +`ExampleKind`, formatter candidates, setting IDs, XML values and telemetry |
| 47 | +identities unchanged. Explicit display mappings live in `src/l10n/display.ts` |
| 48 | +and `src/formatter-settings/assets/labels.ts`. Never persist translated labels. |
| 49 | +For sentences containing links or React nodes, use reorderable placeholders |
| 50 | +with `richText` (browser) or `formatHtml` (native HTML) and trusted nodes. |
| 51 | +Translations must not supply arbitrary HTML or command URLs. |
| 52 | + |
| 53 | +## Updating or adding a language |
| 54 | + |
| 55 | +1. Use a VS Code locale name, such as `zh-cn`, in both |
| 56 | + `package.nls.<locale>.json` and `l10n/bundle.l10n.<locale>.json`. |
| 57 | +2. Keep English defaults in `package.nls.json`. After editing native or browser |
| 58 | + messages, run `npm run l10n:export` to deterministically regenerate |
| 59 | + `l10n/bundle.l10n.json`. This command intentionally updates the source catalog. |
| 60 | +3. Translate every source key in both locale catalogs. Preserve placeholder |
| 61 | + names and occurrence counts, but reorder them as needed. Preserve link |
| 62 | + targets, encoded arguments, Markdown, codicons and functional symbols. |
| 63 | +4. Run `npm run l10n:check`, `npm test` and `npm run build`. The check discovers |
| 64 | + every shipped locale, requires matching manifest/runtime locales, verifies |
| 65 | + coverage and invariants, and extracts to a temporary directory to detect |
| 66 | + drift without rewriting committed catalogs. Add regression cases for new |
| 67 | + UI/action behavior. |
| 68 | +5. Package with `npx @vscode/vsce@latest package -o vscode-java-pack-localized.vsix`. |
| 69 | + Inspect the actual VSIX, not just the checkout: `extension/` must contain |
| 70 | + both root manifest catalogs, runtime bundles and all eight browser assets. |
| 71 | + `node_modules` is intentionally excluded; browser localization is bundled. |
| 72 | + Install the package and verify English, the new language and unsupported |
| 73 | + language fallback, including link actions and restored panels. |
| 74 | + |
| 75 | +### UI validation |
| 76 | + |
| 77 | +Use AutoTest YAML, stable command IDs/selectors and deterministic text verifiers. |
| 78 | +`test-plans/java-webview-migration.yaml` covers the current English command routes; |
| 79 | +`test-plans/localization-en.yaml` and `test-plans/localization-zh-cn.yaml` select |
| 80 | +`setup.locale: en` / `zh-cn` explicitly. Both top-level plans are discovered by |
| 81 | +the existing CI matrix on Windows, Linux and macOS. CI resolves npm's |
| 82 | +`@vscjava/vscode-autotest@latest` once per workflow run, validates and publishes |
| 83 | +the returned version, then installs that exact version in every test and |
| 84 | +aggregate job. Jobs do not independently resolve latest. Runner failures retain |
| 85 | +their nonzero exit codes and fail the matrix job rather than becoming manual-only |
| 86 | +or soft-failed checks. |
| 87 | + |
| 88 | +AutoTest 0.7.36 supports `setup.locale` / `--locale` and checks the actual |
| 89 | +`vscode.env.language` before any scenario step. The Chinese plan installs |
| 90 | +`MS-CEINTL.vscode-language-pack-zh-hans`; installing a language pack alone is |
| 91 | +not locale selection. Both plans reference `config/localization.json` using |
| 92 | +`setup.vscodeConfig`, which opts into owned, per-run user-data and extension |
| 93 | +directories and a copied fixture workspace without changing the normal IDE. |
| 94 | +The shared JSON supplies the stable VS Code version and raw user/workspace |
| 95 | +settings. Plans keep localized UI labels separate from command IDs and settings. |
| 96 | + |
| 97 | +For the two macOS locale CI cases, the workflow sets `TMPDIR` to the existing |
| 98 | +job-owned `RUNNER_TEMP` before starting AutoTest. The canonical default macOS |
| 99 | +temp directory otherwise makes the runner's isolated profile path exceed |
| 100 | +VS Code's 103-character Unix IPC socket limit and abort before the first window. |
| 101 | +Profiles still use unique per-run directories; no normal IDE profile, runner |
| 102 | +installation, launch flags, locale assertions or failure exits are changed. |
| 103 | + |
| 104 | +Run both scenarios against the packaged extension. These reproducible commands |
| 105 | +pin the actually qualified runner, AutoTest 0.7.36; CI uses latest as described |
| 106 | +above: |
| 107 | + |
| 108 | +```powershell |
| 109 | +npx -y @vscjava/vscode-autotest@0.7.36 run test-plans\localization-en.yaml --vsix vscode-java-pack-localized.vsix --no-llm --analysis-mode evidence-only --output test-results\localization-en --logs |
| 110 | +npx -y @vscjava/vscode-autotest@0.7.36 run test-plans\localization-zh-cn.yaml --vsix vscode-java-pack-localized.vsix --no-llm --analysis-mode evidence-only --output test-results\localization-zh-cn --logs |
| 111 | +``` |
| 112 | + |
| 113 | +Inspect `results.json`'s `vscodeLocale.requested` and `vscodeLocale.actual`, |
| 114 | +step results, logs and screenshots. YAML validation and English results alone |
| 115 | +do not prove Chinese installed-package behavior. Each locale plan asserts |
| 116 | +positive and wrong-language text on all seven currently routable pages, |
| 117 | +preserves product names/Java examples, verifies raw AWT and formatter setting |
| 118 | +effects, and performs a real Help Center reload with restored title/content. |
| 119 | + |
| 120 | +Installed-package qualification on Windows with VS Code 1.145.2 and AutoTest |
| 121 | +0.7.36 passed all 31 steps in each locale, with no failures, errors or skips. |
| 122 | +Both reports confirmed the requested native language (`en` and `zh-cn`). |
| 123 | +The successful runs include the original Welcome tab, all seven public pages, |
| 124 | +positive/wrong-language content checks, the translated Project Settings |
| 125 | +Command Palette caption, AWT/formatter setting effects and Help Center |
| 126 | +reload/restoration. These Windows results do not establish Linux/macOS |
| 127 | +qualification or the separate release gates below. |
| 128 | + |
| 129 | +The runner has 12 command-and-argument keybinding slots; evidence capture |
| 130 | +requires one. The plans reserve it by using the localized Project Settings |
| 131 | +palette caption for that route, and dismiss transient context menus before |
| 132 | +returning focus to the workbench. These steps do not suppress test failures. |
| 133 | + |
| 134 | +VS Code also suppresses notification toasts when launched with |
| 135 | +`--enable-smoke-test-driver`, which AutoTest uses. The English native scenario |
| 136 | +therefore checks the AWT commands' persisted settings instead of claiming toast |
| 137 | +coverage. The Chinese plan does the same; selecting Chinese does not remove |
| 138 | +this separate limitation. Formatter plans preconfigure a profile and verify |
| 139 | +checkbox setting effects, not suppressed native Yes/No prompts. |
| 140 | +Check the English and Chinese native messages and formatter actions in a normal |
| 141 | +installed VS Code session before release. Node tests cover translated action |
| 142 | +identity, cancellation and reordered message placeholders, not actual toast UI. |
| 143 | + |
| 144 | +The legacy Runtime serializer and all eight current-language HTML bootstraps |
| 145 | +also have executable Node regression coverage. The English native scenario |
| 146 | +exercises a real Help Center window reload and restored content/title, as does |
| 147 | +the Chinese scenario. Genuine installed legacy Runtime restoration, installed |
| 148 | +VS Code 1.74 behavior and actual unsupported-locale fallback remain separate |
| 149 | +release gates; synthetic missing-key/bundle and minimum-API tests do not replace |
| 150 | +them. Independent human Chinese review remains required below. |
| 151 | + |
| 152 | +### Development-only pseudolocalization |
| 153 | + |
| 154 | +Use the standard `@vscode/l10n-dev` tooling with VS Code's Pseudo Language |
| 155 | +Language Pack to find clipping and concatenated sentences. In a disposable |
| 156 | +development checkout, run: |
| 157 | + |
| 158 | +```powershell |
| 159 | +node node_modules\@vscode\l10n-dev\dist\cli.js generate-pseudo package.nls.json l10n\bundle.l10n.json |
| 160 | +``` |
| 161 | + |
| 162 | +This writes adjacent `qps-ploc` catalogs. Use them only in that disposable |
| 163 | +checkout, select the Pseudo display language, and reload normally. Never commit, |
| 164 | +publish or include these generated catalogs in the release VSIX; they are not |
| 165 | +a supported production language. Inspect long labels, accessibility names and |
| 166 | +trusted rich-text links as well as overall layout. |
| 167 | + |
| 168 | +## Scope |
| 169 | + |
| 170 | +Release notes, README/tutorial prose, external documentation, screenshots, SVG |
| 171 | +content and embedded walkthrough media (including `walkthrough/runtime.md`) are |
| 172 | +not translated. Pack-owned in-webview UI text and manifest media alternative |
| 173 | +text are translated. Bundled extensions retain their own localization ownership. |
| 174 | + |
| 175 | +## Translation review |
| 176 | + |
| 177 | +Human review by an independent Simplified Chinese speaker is a release gate; |
| 178 | +catalog checks do not establish translation quality. Do not automatically publish |
| 179 | +machine translations or call a cloud translation service. Use consistent terms: |
| 180 | +runtime = 运行时, project = 项目, classpath = 类路径, formatter = 格式化程序. |
| 181 | +Keep Java, JDK, VS Code and extension/product names unchanged. Future |
| 182 | +right-to-left languages also require explicit layout qualification. |
0 commit comments