Skip to content

Commit 1898fa2

Browse files
chagongCopilot
andauthored
Add multilingual Java Pack UI with Simplified Chinese support (#1791)
* feat: add multilingual Java Pack UI Localize the manifest, extension-host messages and all eight webviews using VS Code's display language. Add Simplified Chinese catalogs and extraction/regression guards while preserving raw command, setting and telemetry values. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * test: require localization bootstrap in restored webviews Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * test: run localized UI coverage with AutoTest 0.7.36 Promote English and Chinese scenarios into CI discovery, verify native locales and deterministic actions/restoration, and document installed-VSIX results. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix: shorten isolated macOS locale CI profiles Use the existing job-owned RUNNER_TEMP for the two macOS locale cases to avoid oversized VS Code Unix IPC socket paths. Preserve per-run isolation, all locale assertions, the OS matrix and failure propagation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix: resolve latest AutoTest once per CI run Resolve the npm latest release in discovery and retain validation plus exact shared-version installation in every test and aggregate job. Update guards and CI documentation without changing historical 0.7.36 qualification records. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent caf653f commit 1898fa2

87 files changed

Lines changed: 4742 additions & 810 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/e2e-autotest.yml‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ jobs:
7575
with:
7676
node-version: 22
7777

78-
- name: Resolve AutoTest version for this run
78+
- name: Resolve latest AutoTest version for this run
7979
id: autotest
8080
shell: bash
8181
run: |
@@ -517,6 +517,15 @@ jobs:
517517
$autotestArgs += "--pre-release"
518518
}
519519
520+
# macOS's default temp path makes the isolated profile's VS Code IPC
521+
# socket exceed 103 characters. Keep the profile unique but its root short.
522+
if ($env:RUNNER_OS -eq "macOS" -and "${{ matrix.plan }}" -in @("localization-en", "localization-zh-cn")) {
523+
if (-not $env:RUNNER_TEMP -or -not (Test-Path -LiteralPath $env:RUNNER_TEMP -PathType Container)) {
524+
throw "The localization run requires an existing RUNNER_TEMP directory."
525+
}
526+
$env:TMPDIR = $env:RUNNER_TEMP
527+
}
528+
520529
Write-Host "Running: autotest $($autotestArgs -join ' ')"
521530
$consoleLog = Join-Path $env:AUTOTEST_STAGING_DIR "console.log"
522531
$PSNativeCommandUseErrorActionPreference = $false

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,11 @@ Each extension mentioned above is a separate open-source project and has its own
7171

7272
This extension collects telemetry data to help us improve the Java development experience in VS Code. It does not collect any personal information such as names, addresses, or file paths. For more details, see our [privacy statement](http://go.microsoft.com/fwlink/?LinkId=521839). You can disable telemetry collection at any time by changing the `telemetry.enableTelemetry` setting as described in our [FAQ](https://code.visualstudio.com/docs/supporting/faq#_how-to-disable-telemetry-reporting).
7373

74+
## Contributing translations
75+
76+
See the [localization contributor guide](docs/localization.md) for supported
77+
resources, catalog checks and translation review requirements.
78+
7479
## License
7580

7681
[MIT](https://github.com/Microsoft/vscode-java-pack/blob/master/LICENSE.txt)

‎docs/localization.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
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

Comments
 (0)