[5.2.x] Fixed #35993 -- Documented gettext f-string support limitations.

Thank you to Claude Paroz and Athena Wolfskämpf for the review.

Backport of 2c2f09055579cc6068cae6c6fd3135011d6df4f1 from main.

1 files changed, 16 insertions, 2 deletions

diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt
index 04dad034cc..eacf2a3234 100644
--- a/docs/topics/i18n/translation.txt
+++ b/docs/topics/i18n/translation.txt
@@ -129,8 +129,22 @@ have more than a single parameter. If you used positional interpolation,
 translations wouldn't be able to reorder placeholder text.
 
 Since string extraction is done by the ``xgettext`` command, only syntaxes
-supported by ``gettext`` are supported by Django. In particular, Python
-:py:ref:`f-strings <f-strings>` are not yet supported by ``xgettext``, and
+supported by ``gettext`` are supported by Django. Python :py:ref:`f-strings
+<f-strings>` cannot be used directly with ``gettext`` functions because
+f-string expressions are evaluated before they reach ``gettext``. This means
+``_(f"Welcome {name}")`` will not work as expected, as the variable is
+substituted before translation occurs. Instead, use named-string
+interpolation::
+
+    # Good
+    _("Welcome %(name)s") % {"name": name}
+
+    # Good
+    _("Welcome {name}").format(name=name)
+
+    # Bad
+    _(f"Welcome {name}")  # f-string evaluated before translation.
+
 JavaScript template strings need ``gettext`` 0.21+.
 
 .. _translator-comments: