This repository contains the source for durable-workflow.com, including the current Durable Workflow 2.0 documentation, the versioned 1.x documentation, the blog, and public protocol references.
Use Node.js 24 and npm:
npm ci
npm run startBuild the same static site and validate the same links as CI:
npm run buildnpm run check:dependency-security checks the recorded dependency version
floors, blocked build-asset formats and stale HTTP-cache wildcard handling.
Run npm audit separately for current advisories. Passing this preflight does
not mean every dependency is free of reported vulnerabilities.
The unpatched braces advisory affects build/development glob processing. This repository supplies those patterns from reviewed source and configuration; it has no public pattern evaluation endpoint, and the published site is static. Maintainers accept that limited build-tool exposure while no patched release is available and keep the audit warning visible. Review the decision when an upstream fix is released, or before accepting external patterns or changing development-server exposure and build-source permissions. The dependency paths and review are recorded in #261.
English is the default locale. The offered documentation languages are Ukrainian
(/uk/), Spanish (/es/), Brazilian Portuguese (/pt-BR/), Simplified Chinese
(/zh-Hans/), Japanese (/ja/), French (/fr/) and German (/de/).
Current 2.0 guides must have reviewed translations in every offered language.
Completing the existing gaps is tracked in #169.
The visible English fallback remains a temporary indication of missing work,
not completed language support. Blog articles and versioned 1.x documentation
have separate English-only scope.
Preview one locale with:
npm run start -- --locale uk
npm run start -- --locale es
npm run start -- --locale pt-BR
npm run start -- --locale zh-Hans
npm run start -- --locale ja
npm run start -- --locale fr
npm run start -- --locale deTranslate current docs in i18n/<locale>/docusaurus-plugin-content-docs/current/
and standalone pages in i18n/<locale>/docusaurus-plugin-content-pages/. Keep the
English source file paths, examples, commands, API names and explicit heading
anchors intact. Ukrainian keeps workflow, activity, worker, signal, timer,
query, update and saga as English technical terms. Spanish uses workflow and
worker, with actividad, señal, temporizador, consulta and actualización in
prose. Brazilian Portuguese keeps workflow, worker, namespace and replay, with
atividade, sinal, temporizador, consulta and atualização in prose. Simplified
Chinese uses 工作流, 活动, 信号, 定时器, 查询, 更新, 命名空间 and 重放, while keeping
Worker and product names. Japanese uses ワークフロー, アクティビティ, シグナル,
タイマー, クエリ, 更新, 名前空間, リプレイ, 決定性 and 冪等性, while keeping
Worker and product names. French keeps workflow and worker, with activité,
signal, temporisateur, requête de lecture, mise à jour, espace de noms, relecture,
déterminisme and idempotence in prose. German keeps Workflow, Worker, Namespace,
Replay and product names, with Aktivität, Signal, Timer, Abfrage, Update,
Determinismus and Idempotenz in prose. Never translate identifiers in code,
protocol fields or type names.
Use Docusaurus translation markers for component text. Run
npm run write-translations -- --locale uk to extract new messages, then
translate them in i18n/<locale>/code.json and the plugin message files. Build
all locales with npm run build before submitting a change.
When changing or adding an English guide, review and update all seven translations in the same delivery. Review the prose for fluent language and the technical contract for accuracy. Keep executable code blocks identical to the English source. The build checks this for Spanish, Brazilian Portuguese, Simplified Chinese, Japanese, French and German. A missing translation or English fallback does not satisfy a changed guide's acceptance. Artifact version placeholders stay shared with English and update automatically.
The documentation maintainers own translation upkeep. Pull-request and main builds compare changed English guides with all seven translated files and their reviewed source hashes. Missing files, unchanged English copies and stale or missing review hashes fail qualification. Existing executable-example checks remain in place. During completion of #169, unchanged older gaps are still reported separately and are not claimed as translated.
After reviewing a guide, record its English file's SHA-256 in the corresponding
i18n/<locale>/source-hashes.json. Use --record-review only after reviewing
every page it records. Recording hashes alone does not review the prose.
For a local changed-guide check, set DOCS_TRANSLATION_BASE to the full Git
commit SHA of the comparison base before running the normal build.
The pinned Docusaurus 3.10.2 utility patch resolves relative Markdown links between translated and English fallback files. It uses Docusaurus's document map and preserves strict missing-link checks and version boundaries. The build exercises both directions. Recheck and remove the patch when upgrading Docusaurus if the upstream resolver handles these cases.
plugins/local-search.js selects the existing search plugin's Chinese word
segmentation for zh-Hans and Japanese segmentation for ja, combined with
English stemming for API terms and fallback pages. French combines the existing
French and English stemmers, including accented words. German combines German
and English stemming, including umlauts and inflected words. Other locales retain the
default tokenizer. Japanese uses the plugin's existing TinySegmenter.
The pinned search plugin patch resets its index-builder language cache between
locales, because Docusaurus builds all locales in one process. The build checks
English → Chinese → English indexing and serialized-index reloads, including
Chinese words, Ukrainian text and English API terms. The patch also selects
the Japanese query tokenizer when Japanese and English are combined. A focused
test uses the actual browser tokenizer to check unspaced Japanese phrases,
English stemming, index reloads and a switch back to English. The French check
also uses the browser tokenizer and serialized indexes to verify accented
inflections, English API terms and a switch back to English. The German check
covers umlauts, singular/plural forms and the same index reload and language
switch. Recheck this patch
when upgrading the search plugin and remove it when upstream handles these cases.
For a new locale, qualify installation, a completed first workflow, core concepts, safe recovery, navigation, search, language switching and fallback before publication. Check representative pages in a browser, including mobile, and verify canonical and alternate-language links. Spanish, Brazilian Portuguese, Simplified Chinese, Japanese, French and German are delivered increments in #169. Country totals alone do not establish a reader's preferred language. Waterline's additional interface languages are tracked separately in #157.
| Path | Purpose |
|---|---|
docs/ |
Current 2.0 documentation |
versioned_docs/ |
Maintained 1.x documentation snapshot |
blog/ |
Durable Workflow articles |
src/ |
Docusaurus pages, components, theme overrides, and styling |
static/ |
Public images, installers, and machine-readable protocol artifacts |
Pushes to main deploy through GitHub Pages after the documentation build
passes. Protocol contracts have a separate focused validation workflow.
See the organization contribution guide before opening a pull request.