Improve docs regarding RTL migration (#32771)

* docs(migrations): add a note regarding migration from v4 used for RTL layouts

* docs(RTL): LTR & RTL at the same time

* docs(utilities): how-to use the API to rename utilities

* docs(RTL): mention issue when nesting styles with .ltr / .rtl

3 files changed, 58 insertions, 1 deletions

diff --git a/site/content/docs/5.0/getting-started/rtl.md b/site/content/docs/5.0/getting-started/rtl.md
index cd209298b4..4ade8359c3 100644
--- a/site/content/docs/5.0/getting-started/rtl.md
+++ b/site/content/docs/5.0/getting-started/rtl.md
@@ -136,6 +136,42 @@ $font-family-sans-serif:
   "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji" !default;
 ```
 
+### LTR and RTL at the same time
+
+Need both LTR and RTL on the same page? Thanks to [RTLCSS String Maps](https://rtlcss.com/learn/usage-guide/string-map/), this is pretty straightforward. Wrap your `@import`s with a class, and set a custom rename rule for RTLCSS:
+
+```scss
+/* rtl:begin:options: {
+  "autoRename": true,
+  "stringMap":[
+    "name": "ltr-rtl",
+    "priority": 100,
+    "search": ["ltr"],
+    "replace": ["rtl"],
+    "options": {
+      "scope": "*",
+      "ignoreCase": false
+    }
+  ]
+} */
+.ltr {
+  @import "../node_modules/bootstrap/scss/bootstrap";
+}
+/*rtl:end:options*/
+```
+
+After running Sass then RTLCSS, each selector in your CSS files will be prepended by `.ltr`, and `.rtl` for RTL files. Now you're able to use both files on the same page, and simply use `.ltr` or `.rtl` on your components wrappers to use one or the other direction.
+
+{{< callout warning >}}
+#### Edge cases and known limitations
+
+While this approach is understandable, please pay attention to the following:
+
+1. When switching `.ltr` and `.rtl`, make sure you add `dir` and `lang` attributes accordingly.
+2. Loading both files can be a real performance bottleneck: consider some [optimization]({{< docsref "/customize/optimize" >}}), and maybe try to [load one of those files asynchronously](https://www.filamentgroup.com/lab/load-css-simpler/).
+3. Nesting styles this way will prevent our `form-validation-state()` mixin from working as intended, thus require you tweak it a bit by yourself. [See #31223](https://github.com/twbs/bootstrap/issues/31223).
+{{< /callout >}}
+
 ## The breadcrumb case
 
 The [breadcrumb separator]({{< docsref "/components/breadcrumb" >}}/#changing-the-separator) is the only case requiring its own brand new variable— namely `$breadcrumb-divider-flipped` —defaulting to `$breadcrumb-divider`.
diff --git a/site/content/docs/5.0/migration.md b/site/content/docs/5.0/migration.md
index 0f15282a99..5be6c6fa1b 100644
--- a/site/content/docs/5.0/migration.md
+++ b/site/content/docs/5.0/migration.md
@@ -50,7 +50,9 @@ Horizontal direction sensitive variables, utilities and mixins are renamed with
 - Renamed `.pl-*` and `.pr-*` to `.ps-*` and `.pe-*`.
 - Renamed `.text-left` and `.text-right` to `.text-start` and `.text-end`.
 
-Breakpoints specific variants are consequently renamed too (eg. `.text-md-start` replaces `.text-md-left`).
+Breakpoints specific variants are consequently renamed too (e.g. `.text-md-start` replaces `.text-md-left`).
+
+**Note**: if you used v4 to make RTL pages, ensure to reverse changes mentioned above: e.g. use `.*-start` were you used `.*-right`.
 
 ##### Mixins
 
diff --git a/site/content/docs/5.0/utilities/api.md b/site/content/docs/5.0/utilities/api.md
index 7cd002faf4..ecd80af5b9 100644
--- a/site/content/docs/5.0/utilities/api.md
+++ b/site/content/docs/5.0/utilities/api.md
@@ -289,6 +289,25 @@ $utilities: map-merge(
 );
 ```
 
+#### Rename utilities
+
+Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting `class` of a given utility—for example, to rename `.ms-*` utilities to oldish `.ml-*`:
+
+```scss
+@import "bootstrap/scss/functions";
+@import "bootstrap/scss/variables";
+@import "bootstrap/scss/utilities";
+
+$utilities: map-merge(
+  $utilities, (
+    "margin-start": map-merge(
+      map-get($utilities, "margin-start"),
+      ( class: ml ),
+    ),
+  )
+);
+```
+
 ### Remove utilities
 
 Remove any of the default utilities by setting the group key to `null`. For example, to remove all our `width` utilities, create a `$utilities` `map-merge` and add `"width": null` within.