diff --git a/README.md b/README.md
index befb7d3f5..ed1700a29 100644
--- a/README.md
+++ b/README.md
@@ -427,7 +427,8 @@ bun run tauri:build    # builds the app — needs Rust, the Tauri CLI and webvie
 
 ## Languages
 
-**Every map speaks 11 languages** — add `?lang=<code>` to a map's page address. Arabic reads right to left.
+**Every map speaks 11 languages** — add `?lang=<code>` to a map's page address, or, when a map is embedded in
+your own page, set `"locale"` in its `profile-config`. Arabic reads right to left.
 
 ![UPG-100 List in Arabic, right to left](documentation/readme-images/lang-arabic-upg100.png)
 
@@ -447,10 +448,18 @@ bun run tauri:build    # builds the app — needs Rust, the Tauri CLI and webvie
 
 - **Pick a language with the address:** `…/prayer/index.html?lang=fr` shows the map in French. It
   works on every map's own page and on the Research Gallery. `?locale=` works too.
-- **Without it,** a map follows the page's own language (`<html lang>`, which WordPress sets), and
+- **Set it from your own page:** when you embed the Research Gallery or a single map with the
+  JavaScript embed, put the language in its `profile-config` (`"lang"` works too). Set it again
+  later and the map switches language live.
+
+  ```html
+  <doxa-maps-spa profile-config='{"locale":"ar"}'></doxa-maps-spa>
+  ```
+- **Without either,** a map follows the page's own language (`<html lang>`, which WordPress sets), and
   otherwise shows English.
-- **Right to left:** in Arabic the whole layout mirrors — the Research Gallery's tab rail moves to
-  the right.
+- **Right to left:** in Arabic the map's layout mirrors — the Research Gallery's tab rail moves to
+  the right. Set through `profile-config`, only the map's own box mirrors; the rest of your page is
+  left alone. A `?lang=ar` address mirrors the whole page, which is what a map's own page wants.
 - **Where the words live:** `library/i18n/locales/<code>/`, one folder per language. Adding a
   language: [documentation/architecture/i18n.md](./documentation/architecture/i18n.md).