English docs are authored in openclaw/openclaw.
The source docs tree lives under docs/.
The source repo no longer keeps committed generated locale trees such as docs/zh-CN/**, docs/ja-JP/**, docs/es/**, docs/pt-BR/**, docs/ko/**, docs/de/**, docs/fr/**, docs/ar/**, docs/it/**, docs/tr/**, docs/uk/**, docs/id/**, or docs/pl/**.

End-to-end flow

Edit English docs in openclaw/openclaw.
Push to main.
openclaw/openclaw/.github/workflows/docs-sync-publish.yml mirrors the docs tree into openclaw/docs.
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.
openclaw/docs/.github/workflows/translate-zh-cn.yml refreshes docs/zh-CN/** once a day, on demand, and after source-repo release dispatches.
openclaw/docs/.github/workflows/translate-ja-jp.yml does the same for docs/ja-JP/**.
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-tr.yml, translate-uk.yml, translate-id.yml, and translate-pl.yml do the same for docs/es/**, docs/pt-BR/**, docs/ko/**, docs/de/**, docs/fr/**, docs/ar/**, docs/it/**, docs/tr/**, docs/uk/**, docs/id/**, and docs/pl/**.

Why the split exists

Keep generated locale output out of the main product repo.
Keep Mintlify on a single published docs tree.
Preserve the built-in language switcher by letting the publish repo own generated locale trees.

Files in this folder

glossary.<lang>.json — preferred term mappings used as prompt guidance.
zh-Hans-navigation.json — curated zh-Hans Mintlify locale navigation reinserted into the publish repo during sync.
ar-navigation.json, de-navigation.json, es-navigation.json, fr-navigation.json, id-navigation.json, it-navigation.json, ja-navigation.json, ko-navigation.json, pl-navigation.json, pt-BR-navigation.json, tr-navigation.json — starter locale metadata kept alongside the source repo, but the publish sync now clones the full English nav tree for these locales so translated pages are visible in Mintlify without hand-maintaining per-locale nav JSON.
<lang>.tm.jsonl — translation memory keyed by workflow + model + text hash.

In this repo, generated locale TM files such as docs/.i18n/zh-CN.tm.jsonl, docs/.i18n/ja-JP.tm.jsonl, docs/.i18n/es.tm.jsonl, docs/.i18n/pt-BR.tm.jsonl, docs/.i18n/ko.tm.jsonl, docs/.i18n/de.tm.jsonl, docs/.i18n/fr.tm.jsonl, docs/.i18n/ar.tm.jsonl, docs/.i18n/it.tm.jsonl, docs/.i18n/tr.tm.jsonl, docs/.i18n/uk.tm.jsonl, docs/.i18n/id.tm.jsonl, and docs/.i18n/pl.tm.jsonl are intentionally no longer committed.

Glossary format

glossary.<lang>.json is an array of entries:

{
  "source": "troubleshooting",
  "target": "故障排除"
}

Fields:

source: English (or source) phrase to prefer.
target: preferred translation output.

Translation mechanics

scripts/docs-i18n still owns translation generation.
Doc mode writes x-i18n.source_hash into each translated page.
Each publish workflow precomputes a pending file list by comparing the current English source hash to the stored locale x-i18n.source_hash.
If the pending count is 0, the expensive translation step is skipped entirely.
If there are pending files, the workflow translates only those files.
The publish workflow retries transient model-format failures, but unchanged files stay skipped because the same hash check runs on each retry.
The source repo also dispatches zh-CN, ja-JP, es, pt-BR, ko, de, fr, ar, it, tr, uk, id, and pl refreshes after published GitHub releases so release docs can catch up without waiting for the daily cron.

Operational notes

Sync metadata is written to .openclaw-sync/source.json in the publish repo.
Source repo secret: OPENCLAW_DOCS_SYNC_TOKEN
Publish repo secret: OPENCLAW_DOCS_I18N_OPENAI_API_KEY
If locale output looks stale, check the matching Translate <locale> workflow in openclaw/docs first.