morningman opened a new pull request, #4287: URL: https://github.com/apache/doris-website/pull/4287
## Summary Adding a language to this site currently means editing code. The locale list, a locale's label and `htmlLang`, its opt-in flag, the bare-docs redirect, the status-plugin gate, the localization directory, the search analyzer and its labels and cache key, every manifest name, the render path's managed locale, the homepage link helpers, the translation notices, the doc content language, the alternate-language metadata, the locale dropdown, the search version paths, the search identifier fallback, the AI widget labels, the illustration frames and one navbar link each name Japanese. A second language could only be added by copying that code. This makes the locale set configuration. It supersedes #4284 and #4286, whose commits are included here alongside a third one; both are closed in favour of this PR. ### 1. Build only the locales a change can affect `build:locales` accepts `--locales <csv>` and narrows the configured plan to that selection. The configured order is preserved, so a selection containing the default locale still builds it first and keeps the root control files; a selection without it assembles a locale-only tree instead of promoting one language to the root. Unknown, empty or duplicated selections fail before any build starts, and omitting the option still builds every enabled locale, which publishing needs. `verify-static` gains `--partial` for those subset artifacts: assertions about the current locale itself (status notice, body language, canonical, sitemap and search-index membership, noindex, heading IDs) are unchanged, while a counterpart page the subset did not build is counted as skipped. Publishing keeps verifying the complete site without the flag, where a missing counterpart stays a failure, and the scope detector reports whether a build covered every configured locale so the pull-request check relaxes only the comparison it cannot make. Measured on a GitHub `ubuntu-latest` runner (`DOCS_VERSIONS=current`): en 128s, zh-CN 128s, ja 103s. A Japanese-only PR drops from 359s to 103s of locale build time, about **71%**. ### 2. A locale registry drives the build and render path `config/i18n.js` becomes the single registry: each locale declares its code, label, `htmlLang`, whether it is still opt-in, and whether its ordinary pages are translated. `docusaurus.config.js` derives the locale list, the locale configs, the bare-docs redirect and the status plugin from it, so **a new locale is one line**. An introduced locale stays behind `DORIS_ENABLE_LOCALES` (CI enables exactly the locales in scope) or its own `DORIS_ENABLE_<LANG>` flag, so `DORIS_ENABLE_JA` and every publishing workflow keep working unchanged. The render path follows it: the docs adapter resolves its managed locales from `translations/config.json` and iterates them instead of a constant, the search plugin takes its locale, analyzer language, routes, cache key and summary name from configuration (the Japanese context labels move into `searchContextLabels`, byte-for-byte the strings they replaced), and the status plugin writes one manifest per locale while still building browser route groups from **every** managed locale — filtering those by the current locale dropped `hreflang` from the English pages, and the fixture caught it. `verify-static`, `build-scope` and the deploy workflows stop naming a locale too; `scripts/i18n/managed-locales.cjs` lets publishing verify every managed locale without listing them. ### 3. The browser UI reads the same registry `docusaurus.config.js` publishes two lists through `customFields` — the locales that carry translation state, and the locales whose ordinary pages still come from the default locale — and the UI reads those instead of a language. The translation notices and the "search the source documents" link go through `translate()`, with the existing Japanese wording added verbatim to `i18n/ja/code.json` so the rendered Japanese is unchanged. `lang` attributes and the notice's source link follow the current and default locale; the illustration frames pick their label dictionary by the requested locale; the search identifier fallback keys off the configured tokenizer language, which is what actually splits SQL identifiers. `utils/japanese` becomes `utils/localization`, `JapaneseLink` becomes `LocalizedLink`, and the fallback notice and its stylesheet become `SourceFallback` / `LocalizedNotice`. ## Validation - `node --test scripts/i18n/__tests__/*.test.cjs scripts/__tests__/build-locales.test.cjs`: all pass. New `locale-registry.test.cjs` covers the registry's opt-in gating (both env forms), `managedLocales` intersection, and the route-group/manifest split the fixture regression exercised. - **Byte-identical output for the only managed locale.** A real Japanese build at `5fda1b3f19` produces `.i18n-build/manifests/ja.json` with SHA-256 `3fb55bbd91d49c616ea1733f89e4a64ab1ff70f0ff5bff345639e6df6608fb2b`, exactly the hash the pre-change code produced from the same commit (1,779 pages, 0 differing entries). - **Rendered HTML compared per locale before and after.** All three locales built before and after the frontend change: 6,822 pages each, **zero differing pages** once content-hashed asset names and CSS-module class hashes are normalised. This covers the homepage, docs, community, search and the notice markup. - `node scripts/i18n/verify-fixture.cjs` passes: the real three-language fixture covers stale SQL, unknown changes, approved prose, manual edits, source deletion, Chinese-only sources, separate versions and plugins, links and source timestamps. - `verify-static` on the complete three-locale build: `verified: 1778, skipped: 0`, no reports. On a locale subset: `verified: 1778, skipped: 696`; without `--partial` the same artifact still fails on the missing counterpart. - `config/i18n.js`, the workflows and the fixture parse; the build plan is unchanged with `DORIS_ENABLE_JA=true` and drops `ja` without it. `tsc --noEmit` reports no new diagnostics (the pre-existing `JSX`-namespace and vendored-search-module errors are unchanged). - The four search index files hold the same document sets. Their internal ordering differs, but two **pre-change** builds into different directories differ from each other the same way, so that is pre-existing build non-determinism. ## Not covered The translation pipeline still names Japanese: the model prompts in `translation-engine.cjs`/`codex-adapter.cjs`, the bot identity, branch names, per-locale state paths, and the pinned baseline in `check-translations.cjs`, `audit-coverage.cjs` and `inventory.cjs`. That automation is producing translation PRs right now, so it should be generalized in its own change with its own validation rather than mixed into this one. `src/utils/tokenize.ts` keeps a three-entry table of languages whose lunr tokenizer needs its own segmenter; that is a property of the tokenizer library, not of our locale configuration, and adding a language there is a one-line decision about that language's search quality. `static/.htaccess` keeps one block per locale: it is server configuration rather than application code, and each locale's redirect and 404 policy is a deployment decision. `verify-search.cjs` keeps its hardcoded Japanese queries and UI assertions — they are that scenario's test data, not locale logic — and only its summary artifact reference was updated. ## Versions - [x] dev - [x] 4.x - [x] 3.x - [x] 2.1 or older (build tooling only, no content) ## Languages - [x] Chinese - [x] English - [x] Japanese (build, render and UI paths only, no content change) ## Docs Checklist - [x] Checked by AI - [x] Test Cases Built - [x] Updated required version and language counterparts, or explained why not - [x] If only one language changed, confirmed whether source/translation counterparts need sync 🤖 Generated with [Claude Code](https://claude.com/claude-code) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
