Repository navigation
[docs] Add Ukrainian locale for Durable Workflow 2.0 documentation #161
Description
Primary owning repository
durable-workflow/.github
Required source targets
durable-workflow/durable-workflow.github.io@main
Repository roles
durable-workflow/durable-workflow.github.io: sole producer and publisher of the public docs site. Owns Docusaurus i18n (uk), translated 2.0 docs under i18n/uk/, locale UI chrome, build/deploy qualification, and the live durable-workflow.com surface.
No SDK, Server, CLI, or .github source landings are required: this change does not alter wire protocols, packages, or org automation.
Shared public contract
Default locale remains en.
Additional locale uk is available via Docusaurus locale routing (/uk/…) and a navbar locale dropdown.
In scope: all current (2.0) content under docs/, plus site chrome that users see on the 2.0 docs path (navbar, footer, tagline, homepage CTAs/features, compare page).
Out of scope: versioned_docs/version-1.x/ and blog/ (English fallback on uk is acceptable).
Terminology: Ukrainian prose; keep English product/API terms (workflow, activity, worker, signal, timer, query, update, saga, SDK/CLI names, product names). Code blocks, commands, API paths, and config identifiers stay unchanged.
Markdown links to /docs/… keep their English path form; Docusaurus prefixes the active locale.
npm run build must succeed for both en and uk with the existing broken-link policy (onBrokenLinks: throw).
Source evidence
Site i18n today is English-only: docusaurus.config.js (i18n.locales: ['en']).
https://github.com/durable-workflow/durable-workflow.github.io/blob/main/docusaurus.config.js
2.0 docs live in docs/ (~102 markdown/mdx pages); 1.x is separate under versioned_docs.
https://github.com/durable-workflow/durable-workflow.github.io/tree/main/docs
Docusaurus i18n workflow: write-translations, content under i18n//docusaurus-plugin-content-docs/current/, theme JSON for navbar/footer/sidebar.
Org docs policy: keep 2.0 as the primary documentation surface.
https://github.com/durable-workflow/.github/blob/main/AGENTS.md
No existing open issue for a Ukrainian docs locale (org search: i18n / Ukrainian / translation).
Acceptance criteria by repository
durable-workflow/durable-workflow.github.io
- Branch from main; draft PR opened early.
- uk enabled in i18n.locales with localeConfigs (label: Українська, htmlLang: uk) and navbar localeDropdown.
- Theme/UI strings translated (code.json, navbar, footer, homepage/compare as applicable).
- Every current-version file under docs/ has a Ukrainian counterpart under i18n/uk/docusaurus-plugin-content-docs/current/ (including category.json / sidebar labels in current.json).
- 1.x and blog are not required to be translated; English fallback on /uk/… is OK.
- npm run start -- --locale uk serves translated 2.0 entry points (at least /uk/docs/introduction/).
- npm run build (and docs qualification CI) passes for both locales with no broken-link failures.
- After merge to main, production deploy exposes the locale switcher and Ukrainian 2.0 docs on durable-workflow.com.
Close when Ukrainian 2.0 docs and UI chrome are live, qualification is green, and the PR is linked as completion evidence.
Dependency graph
This issue
└── blocks: PR durable-workflow/durable-workflow.github.io (docs/i18n-uk)
└── blocks: production GitHub Pages deploy of the uk locale
No upstream blockers from other repositories.
No downstream SDK/Server issues required.
Cross-repository intake checks
- I searched every affected repository for an existing authoritative issue.
- The primary owner can make the shared decision without relying on a private database or local mirror.
- Private implementation details are excluded; only public contracts are recorded here.
Activity
rmcdaniel commentedon Oct 6, 2026
Accepted as a documentation-site feature. This repository owns the locale,
content, build and deployment. No shared-repository or SDK change is required.
Keep English as the default and add Ukrainian for current 2.0 documentation and
its site navigation. Preserve executable examples and public API identifiers.
Legacy 1.x documentation and the blog can retain their English content. The
translation must preserve the technical meaning and remain maintainable as the
English documentation changes.
Priority P2. Implementation follows the active runtime release and operator
clarity fixes. Next: establish the locale structure and terminology in an early
draft PR, translate the current pages and UI, qualify both locales under the
existing strict link checks, then verify the locale switcher and translated entry
points on the published site. Keep this issue open until those surfaces are live.
rmcdaniel commentedon Oct 7, 2026
Implementation is underway in draft #167. English remains the default. The draft enables Ukrainian and translates navigation, current sidebar descriptions, introduction, and installation, with the existing examples and heading anchors preserved.
Next: translate the remaining current pages and custom UI, qualify both locales with strict link and anchor checks, then verify the deployed site. The issue stays open until that full scope is published.
rmcdaniel commentedon Oct 7, 2026
Completed in PR #167, merged as
a693e41a3fc547f8eedc214d7d0b4c6f7985ab84.All 102 current documentation pages and site UI are available in Ukrainian. English remains the default. Code examples, commands and API identifiers are preserved. Blogs and 1.x documentation retain their English fallback.
Documentation qualification and production deployment passed on the merged commit, along with the public-boundary and protocol checks.
Live verification on October 7, 2026 confirmed HTTP 200, Ukrainian language metadata and matching translated headings for every current documentation route. Browser checks passed for Ukrainian search, locale switching in both directions, localized links, the comparison page, CLI installer, timer simulator, homepage and mobile rendering, without browser runtime exceptions. The documented Ukrainian development command also served the translated introduction successfully.
Start at the Ukrainian introduction. The merged branch has been deleted and its absence verified.