docs(i18n): document RTL (he/ar) status — translated, excluded from switcher

kwagyeman · claude · kwagyeman · commit d8b4c0f73aab · 2026-06-15T21:35:06.000-07:00
he and ar are translated and build clean but the Shibuya theme has no RTL
support (emits lang= but not dir=rtl, ships no RTL CSS), so they are kept out
of the switcher and redirect until the theme/CSS is fixed. Notes what broke
and the steps to enable them.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/tools/i18n/README.md b/docs/tools/i18n/README.md
@@ -7,6 +7,33 @@ for the multi-language docs build. The language list, switcher, and the
 
 All commands are run from the `docs/` directory.
 
+## RTL languages (he, ar) — translated but NOT in the switcher
+
+Hebrew (`he`) and Arabic (`ar`) are fully translated and committed under
+`locale/he/` and `locale/ar/`, and they build cleanly (no markup errors). They
+are deliberately **left out of `conf.py`'s `html_context["languages"]` switcher
+and out of `static/lang-redirect.js`** because the Shibuya theme has no RTL
+support:
+
+- The build emits `<html lang="he">` / `lang="ar"` but **never sets `dir="rtl"`**,
+  and the theme ships **no RTL stylesheet** (no `[dir=rtl]` rules, no
+  `:lang(he|ar)` rules). Verified: zero `dir=` attributes in the `he`/`ar` HTML.
+- Result: the page renders with **LTR chrome** (sidebar, navbar, text-align,
+  next-steps/changelog cards, list indentation all on the left); only the
+  individual Hebrew/Arabic text runs get the browser's per-run bidi. That is a
+  broken right-to-left reading experience, not a mirrored layout.
+
+To enable them later (theme/CSS work, then uncomment the two entries in
+`conf.py` and `lang-redirect.js`'s `SUBDIRS`/`MAP`):
+
+1. Set `dir="rtl"` on `<html>` for RTL languages — override the theme's
+   `layout.html` (or a `conf.py` hook) keyed on `language in {"he","ar"}`.
+2. Add RTL CSS so the layout mirrors — prefer CSS logical properties
+   (`margin-inline-*`, `padding-inline-*`, `inset-inline-*`) or `[dir=rtl]`
+   overrides for the navbar, sidebar, cards, and figures.
+3. Force `dir="ltr"` on code (`.highlight`, `code`, inline literals) and other
+   LTR snippets so they don't reflow inside the RTL flow.
+
 ## Files
 
 | file | role | committed? |
