From 6514f0784bd91bdce5d86be5fb1df338089db9d7 Mon Sep 17 00:00:00 2001
From: Joshua Chen <sidachen2003@gmail.com>
Date: Mon, 19 Sep 2022 10:59:15 -0400
Subject: [PATCH] docs: add caveat about using Translate in string contexts
 (#8115)

---
 website/docs/i18n/i18n-tutorial.md                        | 8 +++++++-
 .../versioned_docs/version-2.0.1/i18n/i18n-tutorial.md    | 8 +++++++-
 .../versioned_docs/version-2.1.0/i18n/i18n-tutorial.md    | 8 +++++++-
 3 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/website/docs/i18n/i18n-tutorial.md b/website/docs/i18n/i18n-tutorial.md
index b7914e87b4..8e621b2810 100644
--- a/website/docs/i18n/i18n-tutorial.md
+++ b/website/docs/i18n/i18n-tutorial.md
@@ -110,11 +110,17 @@ For any React code you've written yourself: React pages, React components, etc.,
 
 Locate all text labels in your React code that will be visible to your users, and mark them with the translation APIs. There are two kinds of APIs:
 
-- The `<Translate>` component wraps a string as a JSX component;
+- The `<Translate>` component wraps a string as a JSX element;
 - The `translate()` callback takes a message and returns a string.
 
 Use the one that better fits the context semantically. For example, the `<Translate>` can be used as React children, while for props that expect a string, the callback can be used.
 
+:::caution
+
+A JSX element is an _object_, not a string. Using it in contexts expecting strings (such as the children of [`<option>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)) would [coerce it to a string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString), which returns `"[object Object]"`. While we encourage you to use `<Translate>` as JSX children, only use the element form when it actually works.
+
+:::
+
 ```mdx-code-block
 <Tabs>
 <TabItem value="Before">
diff --git a/website/versioned_docs/version-2.0.1/i18n/i18n-tutorial.md b/website/versioned_docs/version-2.0.1/i18n/i18n-tutorial.md
index b7914e87b4..8e621b2810 100644
--- a/website/versioned_docs/version-2.0.1/i18n/i18n-tutorial.md
+++ b/website/versioned_docs/version-2.0.1/i18n/i18n-tutorial.md
@@ -110,11 +110,17 @@ For any React code you've written yourself: React pages, React components, etc.,
 
 Locate all text labels in your React code that will be visible to your users, and mark them with the translation APIs. There are two kinds of APIs:
 
-- The `<Translate>` component wraps a string as a JSX component;
+- The `<Translate>` component wraps a string as a JSX element;
 - The `translate()` callback takes a message and returns a string.
 
 Use the one that better fits the context semantically. For example, the `<Translate>` can be used as React children, while for props that expect a string, the callback can be used.
 
+:::caution
+
+A JSX element is an _object_, not a string. Using it in contexts expecting strings (such as the children of [`<option>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)) would [coerce it to a string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString), which returns `"[object Object]"`. While we encourage you to use `<Translate>` as JSX children, only use the element form when it actually works.
+
+:::
+
 ```mdx-code-block
 <Tabs>
 <TabItem value="Before">
diff --git a/website/versioned_docs/version-2.1.0/i18n/i18n-tutorial.md b/website/versioned_docs/version-2.1.0/i18n/i18n-tutorial.md
index b7914e87b4..8e621b2810 100644
--- a/website/versioned_docs/version-2.1.0/i18n/i18n-tutorial.md
+++ b/website/versioned_docs/version-2.1.0/i18n/i18n-tutorial.md
@@ -110,11 +110,17 @@ For any React code you've written yourself: React pages, React components, etc.,
 
 Locate all text labels in your React code that will be visible to your users, and mark them with the translation APIs. There are two kinds of APIs:
 
-- The `<Translate>` component wraps a string as a JSX component;
+- The `<Translate>` component wraps a string as a JSX element;
 - The `translate()` callback takes a message and returns a string.
 
 Use the one that better fits the context semantically. For example, the `<Translate>` can be used as React children, while for props that expect a string, the callback can be used.
 
+:::caution
+
+A JSX element is an _object_, not a string. Using it in contexts expecting strings (such as the children of [`<option>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option)) would [coerce it to a string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString), which returns `"[object Object]"`. While we encourage you to use `<Translate>` as JSX children, only use the element form when it actually works.
+
+:::
+
 ```mdx-code-block
 <Tabs>
 <TabItem value="Before">