diff --git a/docs/.i18n/README.md b/docs/.i18n/README.md
index 396352fb05a..58becf4829b 100644
--- a/docs/.i18n/README.md
+++ b/docs/.i18n/README.md
@@ -27,7 +27,15 @@ Generated locale trees and live translation memory now live in the publish repo:
 
 - 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.
+- Preserve the built-in language switcher for Mintlify-supported generated locales by letting the publish repo own generated locale trees.
+- Keep generated Thai (`th`) and Persian (`fa`) docs plus translation memory even though Mintlify does not currently accept those codes in `navigation.languages`. Their absence from the built-in docs language picker is a host limitation, not a failed translation run.
+
+## Locale visibility
+
+- Control UI supports `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, and `fa`.
+- Docs translation workflows generate the same non-English locale set in `openclaw/docs`.
+- The Mintlify docs language picker can expose only the locales accepted by Mintlify `navigation.languages`; today that includes Vietnamese (`vi`) and Dutch (`nl`), but not Thai (`th`) or Persian (`fa`).
+- Do not treat missing `th` or `fa` entries in generated `docs/docs.json` as a pipeline failure. Verify their generated folders in `openclaw/docs` instead.
 
 ## Files in this folder
 
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index b40b0946025..e18ba5f5a81 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -83,6 +83,8 @@ The Control UI can localize itself on first load based on your browser locale. T
 - The selected locale is saved in browser storage and reused on future visits.
 - Missing translation keys fall back to English.
 
+Docs translations are generated for the same non-English locale set, but the docs site's built-in Mintlify language picker is limited to the locale codes Mintlify accepts. Thai (`th`) and Persian (`fa`) docs are still generated in the publish repo; they may not appear in that picker until Mintlify supports those codes.
+
 ## Appearance themes
 
 The Appearance panel keeps the built-in Claw, Knot, and Dash themes, plus one browser-local tweakcn import slot. To import a theme, open [tweakcn themes](https://tweakcn.com/themes), choose or create a theme, click **Share**, and paste the copied theme link into Appearance. The importer also accepts `https://tweakcn.com/r/themes/<id>` registry URLs, editor URLs like `https://tweakcn.com/editor/theme?theme=amethyst-haze`, relative `/themes/<id>` paths, raw theme IDs, and default theme names such as `amethyst-haze`.
diff --git a/scripts/docs-sync-publish.mjs b/scripts/docs-sync-publish.mjs
index 09b9042f2c6..929329f0067 100644
--- a/scripts/docs-sync-publish.mjs
+++ b/scripts/docs-sync-publish.mjs
@@ -116,7 +116,8 @@ const GENERATED_LOCALES = [
     tmFile: "fa.tm.jsonl",
     navMode: "clone-en",
     // Mintlify does not currently accept `fa` in navigation.languages.
-    // Preserve generated files/translation memory, but do not publish a nav entry.
+    // Keep generated docs and translation memory so the locale stays available
+    // once the docs host accepts it.
     navigation: false,
   },
   {
@@ -154,7 +155,8 @@ const GENERATED_LOCALES = [
     tmFile: "th.tm.jsonl",
     navMode: "clone-en",
     // Mintlify does not currently accept `th` in navigation.languages.
-    // Preserve generated files/translation memory, but do not publish a nav entry.
+    // Keep generated docs and translation memory so the locale stays available
+    // once the docs host accepts it.
     navigation: false,
   },
 ];