Expand documentation translations beyond English and Ukrainian #169

Objective

Make the documentation useful to more developers while keeping translations accurate as the product changes. The main site supports English (en), German onboarding (de), Spanish onboarding (es), French onboarding (fr), Brazilian Portuguese onboarding (pt-BR), Ukrainian (uk), Japanese onboarding (ja) and Simplified Chinese onboarding (zh-Hans). Untranslated reference pages and 1.x documentation identify their English content.

Spanish delivery

Published through #174 on October 7, 2026, merged main a620f9a9fabe57480ed24631587a69245e56f757. Eleven guides cover deployment choice, installation, the PHP/Python/Rust quickstart, embedded authoring, core concepts, determinism, idempotency and recovery. Home, navigation and search are translated. Examples and technical identifiers match English, with reviewed terminology and meaning.

Source and merged-main documentation, protocol and public-boundary checks pass. Pages deployment passes. Live Chromium checks verify all 11 Spanish routes, metadata, quickstart tabs, accented search, stable anchors, fallback navigation and desktop/mobile language switching. English and Ukrainian remain usable. The maintainer-owned upkeep procedure and source-change notices are in README and the existing build.

Brazilian Portuguese delivery

Published through #182 on October 9, 2026, merged main 541b1fa589fb4b0dbebe3575da8fbdc4fa7f22c1. Eleven guides cover the same complete onboarding/core journey as Spanish, with Portuguese home, navigation, search and sidebar descriptions. Reviewed prose preserves the current English technical contract, executable examples, API identifiers, shared artifact values and heading anchors.

All four source checks and all five merged-main checks pass. Pages deployment passes. Live Chromium checks verify all eleven Portuguese routes, canonical and four alternate-language identities, PHP/Python/Rust quickstart tabs, accented recuperação search, stable anchors, relative fallback links and desktop/mobile language switching. English, Ukrainian and Spanish remain usable. Untranslated reference and 1.x pages visibly identify their English content and link directly to English. README and the existing build now cover upkeep for both Spanish and Portuguese.

Review also corrected the shared parallel-activity example to execute all() and clarified the difference between worker recovery and a terminal workflow failure in all four languages.

Simplified Chinese delivery

Published through #183 on October 9, 2026, merged main 8474b426524433dfd45730491e418ef632aa1373. Eleven guides cover the complete onboarding/core journey, with Chinese home, navigation, search and sidebar descriptions. Reviewed prose preserves English executable examples, technical identifiers, shared artifact values and heading anchors. The shared clock helper now identifies the current v2 API in all five languages.

All four source gates and all five main gates pass. Pages deployment passes. Live Chromium checks verify all eleven Chinese guides on desktop and mobile, canonical and five alternate-language identities, complete PHP/Python/Rust programs, rendered artifact values, stable anchors, relative fallback links, explicit English reference/1.x notices and language switching.

Chinese searches for 恢复, 幂等 and 工作流, plus English activity, pass. Existing English, Ukrainian, Spanish and Portuguese search remains usable. Chinese segmentation uses the existing search plugin, selected per locale. A focused regression covers its language-cache reset and serialized-index reloads. README and the existing build now cover translation upkeep for all three new locales.

French and German are now included following the maintainer's October 9 request.

Japanese delivery

Published through #184 on October 9, 2026, merged main c2b6aa15e1b3361889d4449881c2d88550e046ec. Eleven reviewed guides cover the complete onboarding/core journey, with Japanese home, navigation, search and sidebar descriptions. Executable examples, API identifiers, shared artifact values and explicit heading anchors match English.

All four source gates and all five main gates pass. Pages deployment passes. Actual live Chromium checks verify all eleven Japanese guides on desktop/mobile, canonical and six alternate-language identities, complete PHP/Python/Rust quickstart programs, rendered artifact values, stable anchors, relative links, explicit English reference/1.x notices and direct English navigation.

Japanese 障害復旧, 復旧, 冪等性, ワークフロー and English activity search pass. Existing English, Ukrainian, Spanish, Portuguese and Chinese searches remain usable. Home and desktop/mobile language switching pass without overflow or runtime exceptions. Representative screenshots were inspected.

Japanese uses the existing search library's segmentation combined with English stemming. The pinned plugin patch selects the Japanese browser-query tokenizer when both languages are enabled. A focused actual-tokenizer regression covers unspaced phrases, API terms, serialized-index reloads and a switch back to English. README and the existing source-review/example checks cover upkeep for all four additional delivered locales.

French delivery

Published through #185 on October 9, 2026, merged main
98a8c9c5858fafa4c17d3838d44ab56c1f1f07f9. Eleven reviewed French guides
cover the complete onboarding/core journey, with French home, navigation,
search and sidebar descriptions. English examples, API identifiers, shared
artifact values and explicit heading anchors are preserved.

The seven-locale build, all four source gates and all five main gates pass.
Pages deployment
passes. Actual live Chromium checks verify all eleven French guides on desktop
and mobile, canonical/seven alternate-language identities, full PHP/Python/Rust
programs, rendered published artifact values, stable anchors, relative links,
explicit English reference/1.x notices and direct English navigation.

French échec, reprise, idempotence, activité and English
activity search pass. All six existing locale searches remain usable.
Home and desktop/mobile language switching pass without overflow or runtime
exceptions. Representative screenshots were inspected. French search uses the
existing library's French/English stemmers; the focused actual-tokenizer test
covers accented inflections, serialized indexes and switching back to English.
README and the existing example/source-review checks cover upkeep.

German delivery

Published through #186 on October 9, 2026, merged main
1969046ebae6b43c8f7e8ea23289bc969ab78b4b. Eleven reviewed German guides
cover the complete onboarding/core journey, with German home, navigation,
search and sidebar descriptions. Executable examples, API identifiers,
shared artifact values and explicit heading anchors are preserved.

The eight-locale build, all four source gates and all five main gates pass.
Pages deployment
passes. Actual live Chromium checks verify all eleven German guides on desktop
and mobile, canonical/eight alternate-language identities, complete PHP/Python/Rust
quickstart programs, rendered published artifact values, stable anchors,
relative links, explicit English reference/1.x notices and direct English navigation.

German Wiederherstellung, Überblick, Idempotenz, Aktivität and English
activity search pass. Search remains usable in all seven existing locales.
Home and desktop/mobile language switching pass without overflow or runtime
exceptions. Representative screenshots were inspected. German search uses the
existing library's German/English stemmers; the focused browser-tokenizer test
covers umlauts, inflections, serialized indexes and switching back to English.
README and the existing source-review/example checks cover upkeep.

Language navigation

The picker keeps English first and orders the remaining languages by their
displayed native names: English, Deutsch, Español, Français, Português (Brasil),
Українська, 日本語, 简体中文. This replaces the order in which translations were added.

The configuration change is merged through #187, main
cb8070f6ae621be025232ade005f6b8cfa30eb62. All source/main checks and
Pages deployment
pass. Actual live desktop/mobile checks verify the order and the locale destinations.

Agreed direction

The maintainer requested a language recommendation and then asked for this work to be tracked here.

The agreed delivery sequence was:

1. Spanish (es)
2. Brazilian Portuguese (pt-BR)
3. Simplified Chinese (zh-Hans)
4. Japanese (ja)
5. French (fr)
6. German (de)

All six additional locales are published: Spanish, Brazilian Portuguese, Simplified Chinese, Japanese, French and German. Each includes the same eleven-guide onboarding/core scope, navigation, search, explicit English fallback, source-change checks and live browser qualification. Documentation maintainers own upkeep through the existing build and review instructions.

This ordering is a product judgment, not a measured ranking of our visitors. GitHub’s 2025 Octoverse report provides context about developer communities in China, Brazil and Japan, but country totals alone do not establish documentation language demand.

Work

• Implement locales incrementally through reviewed PRs. Preserve English and Ukrainian.
• Translate the documentation and navigation needed for a complete onboarding journey, including installation, an example, core concepts and safe operational guidance. Keep code, API names, version constraints and protocol contracts exact.
• Obtain fluent language review for terminology and technical meaning. Make any untranslated content or English fallback apparent to readers.
• Keep locale routes, navigation, search and language switching usable, with correct canonical and alternate-language metadata.
• Establish a lightweight way to notice source changes that need translation updates. Keep this with the repository’s existing documentation workflow.
• Use available audience evidence to judge the value of each additional locale before expanding maintenance work.

Acceptance

• Spanish is published and its complete onboarding journey is reviewed and usable.
• Brazilian Portuguese is published and its complete onboarding journey is reviewed and usable.
• Simplified Chinese is published and its complete onboarding journey is reviewed and usable.
• Japanese is published and its complete onboarding journey is reviewed and usable.
• French is published and its complete onboarding journey is reviewed and usable.
• German is published and its complete onboarding journey is reviewed and usable.
• Each delivered locale passes the site build and representative browser checks for navigation, language switching, links and metadata.
• English and Ukrainian remain usable, and translated technical claims match current published behavior.
• Translation upkeep has a clear owner and a repeatable repository workflow.
• The language picker uses an intentional order on desktop and mobile.
• Verify the remaining published routes before closing this issue.

Existing Ukrainian delivery was completed in #161. This issue owns the additional documentation locales. Waterline #157 separately owns these six languages in the operator interface.