mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-18 09:44:46 +00:00
docs: document aggregate translation workflow
This commit is contained in:
Peter Steinberger
@@ -19,9 +19,9 @@ Generated locale trees and live translation memory now live in the publish repo:
|
||||
2. Push to `main`.
|
||||
3. `openclaw/openclaw/.github/workflows/docs-sync-publish.yml` mirrors the docs tree into `openclaw/docs`.
|
||||
4. The sync script rewrites the publish `docs/docs.json` so the generated locale picker blocks exist there even though they are no longer committed in the source repo.
|
||||
5. `openclaw/docs/.github/workflows/translate-zh-cn.yml` refreshes `docs/zh-CN/**` once a day, on demand, and after source-repo release dispatches.
|
||||
6. `openclaw/docs/.github/workflows/translate-zh-tw.yml` and `translate-ja-jp.yml` do the same for `docs/zh-TW/**` and `docs/ja-JP/**`.
|
||||
7. `openclaw/docs/.github/workflows/translate-es.yml`, `translate-pt-br.yml`, `translate-ko.yml`, `translate-de.yml`, `translate-fr.yml`, `translate-ar.yml`, `translate-it.yml`, `translate-vi.yml`, `translate-nl.yml`, `translate-fa.yml`, `translate-tr.yml`, `translate-uk.yml`, `translate-id.yml`, `translate-pl.yml`, and `translate-th.yml` do the same for `docs/es/**`, `docs/pt-BR/**`, `docs/ko/**`, `docs/de/**`, `docs/fr/**`, `docs/ar/**`, `docs/it/**`, `docs/vi/**`, `docs/nl/**`, `docs/fa/**`, `docs/tr/**`, `docs/uk/**`, `docs/id/**`, `docs/pl/**`, and `docs/th/**`.
|
||||
5. `openclaw/docs/.github/workflows/translate-all.yml` waits for `main` to settle, translates only stale or missing locale pages, and uploads per-locale artifacts.
|
||||
6. The publish repo finalizer applies successful locale artifacts and pushes one aggregate `chore(i18n): refresh translations` commit.
|
||||
7. A weekly `full` run reconciles every locale/page path so flaky model failures are retried without making hot docs commits wait.
|
||||
|
||||
## Why the split exists
|
||||
|
||||
|
||||
103
docs/.i18n/translation-workflow.md
Normal file
103
docs/.i18n/translation-workflow.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Translation workflow
|
||||
|
||||
Internal note for the docs publish pipeline. This file is under `docs/.i18n`, which is ignored by the docs-site build and is not published.
|
||||
|
||||
## Goals
|
||||
|
||||
- English docs deploy quickly after every source docs sync.
|
||||
- Locale translation does not run for every hot `main` commit.
|
||||
- Translation work is debounced so a burst of docs commits becomes one translation wave.
|
||||
- Locale jobs translate only pages whose source hash changed since the last successful locale output.
|
||||
- Successful locale outputs are committed together, even if one or more locale jobs fail.
|
||||
- A weekly reconciliation reruns every locale/page path to repair missed or flaky translations.
|
||||
|
||||
## Event flow
|
||||
|
||||
1. `openclaw/openclaw` syncs English docs into `openclaw/docs`.
|
||||
2. GitHub Pages deploys English/source changes immediately from the sync commit.
|
||||
3. `Translate All` is triggered by the sync commit, release dispatch, manual dispatch, or weekly schedule.
|
||||
4. The coordinator waits a short cooldown window before starting translation.
|
||||
5. After the cooldown, the coordinator reads the current `origin/main` source metadata.
|
||||
6. If a newer docs sync arrived during cooldown, the coordinator uses the newer source state.
|
||||
7. Per-locale translation jobs run in parallel with `fail-fast: false`.
|
||||
8. Each locale job uploads an artifact for the requested source SHA.
|
||||
9. The finalizer downloads available artifacts, ignores stale or failed payloads, and pushes one aggregate i18n commit.
|
||||
|
||||
## Debounce policy
|
||||
|
||||
The coordinator waits 5 minutes after a docs sync or release dispatch, then re-reads `origin/main`.
|
||||
|
||||
If `.openclaw-sync/source.json` changed during the wait, it waits again from the newer state. If `main` keeps moving, the wait is capped at 20 minutes and the newest observed state is translated.
|
||||
|
||||
Manual and weekly runs do not wait by default.
|
||||
|
||||
## Incremental translation
|
||||
|
||||
Each translated page stores `x-i18n.source_hash`. Locale jobs compare the current English page hash with the stored locale hash.
|
||||
|
||||
Normal runs translate only:
|
||||
|
||||
- missing locale pages
|
||||
- locale pages with stale `x-i18n.source_hash`
|
||||
- pages affected by source deletion/pruning
|
||||
|
||||
If a locale job fails, its artifact is marked failed and carries no payload. The finalizer still commits successful locales. The failed locale remains stale and is picked up by the next incremental run because its source hashes still do not match.
|
||||
|
||||
## Artifact contract
|
||||
|
||||
Each locale job uploads one artifact named with locale and source SHA:
|
||||
|
||||
```text
|
||||
i18n-zh-cn-<source-sha>
|
||||
```
|
||||
|
||||
Artifact contents:
|
||||
|
||||
```text
|
||||
metadata.json
|
||||
changed-files.txt
|
||||
deleted-files.txt
|
||||
payload/docs/<locale>/**
|
||||
payload/docs/.i18n/<locale>.tm.jsonl
|
||||
```
|
||||
|
||||
`metadata.json` includes the locale, locale slug, source SHA, pending count, changed count, and any failure reason. The finalizer rejects artifacts whose `source_sha` does not match the current `.openclaw-sync/source.json`.
|
||||
|
||||
The source repo release workflow dispatches one `translate-all-release` event. The coordinator still accepts old per-locale release events for compatibility, but those are only a fallback.
|
||||
|
||||
## Aggregate commit
|
||||
|
||||
The finalizer owns the only locale push in the normal path.
|
||||
|
||||
Commit message:
|
||||
|
||||
```text
|
||||
chore(i18n): refresh translations
|
||||
```
|
||||
|
||||
The commit may contain a partial locale set. The job summary lists applied locales, locales with no changes, missing or failed locales, stale artifacts, and invalid artifacts.
|
||||
|
||||
## Weekly reconciliation
|
||||
|
||||
The weekly run uses `full` mode. It forces a full reconciliation across every locale and every source page instead of relying only on changed source hashes.
|
||||
|
||||
Glossary changes also force full reconciliation because glossary guidance can affect pages whose source hashes did not change.
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- regenerate or verify every locale page
|
||||
- prune stale locale pages
|
||||
- refresh translation memory as needed
|
||||
- still use parallel locale jobs
|
||||
- still commit one aggregate result
|
||||
- still tolerate individual locale failures
|
||||
|
||||
The weekly run is the repair mechanism for LLM flakiness, partial failures, and missed incremental updates.
|
||||
|
||||
## Deployment policy
|
||||
|
||||
English deploys from source sync commits.
|
||||
|
||||
Translations deploy from the aggregate i18n commit. A hot docs day should produce many fast English deploys, but only a small number of locale deploys.
|
||||
|
||||
If external deploy providers such as Mintlify watch every push, the aggregate i18n commit is the load reducer. Avoid restoring per-locale pushes to `main`.
|
||||
Reference in New Issue
Block a user