From 0f312b8ad7ddf23410d737b433a8234eebf78560 Mon Sep 17 00:00:00 2001
From: Chiemezuo <chiemezuoakujobi@gmail.com>
Date: Sat, 21 Oct 2023 21:21:25 +0100
Subject: [PATCH] Update contributing translation docs - template usage

Closes #10126
---
 CHANGELOG.txt                     |  1 +
 docs/contributing/translations.md | 39 +++++++++++++++++++++++++++++--
 docs/releases/5.3.md              |  2 +-
 3 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.txt b/CHANGELOG.txt
index bf39b0228c..71e90d973c 100644
--- a/CHANGELOG.txt
+++ b/CHANGELOG.txt
@@ -7,6 +7,7 @@ Changelog
  * Fix: Update system check for overwriting storage backends to recognise the `STORAGES` setting introduced in Django 4.2 (phijma-leukeleu)
  * Fix: Prevent password change form from raising a validation error when browser autocomplete fills in the "Old password" field (Chiemezuo Akujobi)
  * Fix: Ensure that the legacy dropdown options, when closed, do not get accidentally clicked by other interactions wide viewports (CheesyPhoenix)
+ * Docs: Document, for contributors, the use of translate string literals passed as arguments to tags and filters using `_()` within templates (Chiemezuo Akujobi)
  * Maintenance: Update BeautifulSoup upper bound to 4.12.x (scott-8)
  * Maintenance: Migrate initialization of classes (such as `body.ready`) from multiple JavaScript implementations to one Stimulus controller `w-init` (Chiemezuo Akujobi)
 
diff --git a/docs/contributing/translations.md b/docs/contributing/translations.md
index 657a1cf298..9f50dc35d9 100644
--- a/docs/contributing/translations.md
+++ b/docs/contributing/translations.md
@@ -38,11 +38,11 @@ These new translations are imported into Wagtail for any subsequent RC and the f
 
 ## Marking strings for translation
 
-In code, strings can be marked for translation with using Django's [translation system](django:topics/i18n/translation), using `gettext` or `gettext_lazy` in Python and `blocktranslate` and `translate` in templates.
+In code, strings can be marked for translation with using Django's [translation system](django:topics/i18n/translation), using `gettext` or `gettext_lazy` in Python and `blocktranslate`, `translate`, and `_(" ")` in templates.
 
 In both Python and templates, make sure to always use named placeholder. In addition, in Python, only use the printf style formatting. This is to ensure compatibility with Transifex and help translators in their work.
 
-For example:
+### Translations within Python
 
 ```python
 from django.utils.translation import gettext_lazy as _
@@ -68,8 +68,43 @@ _("Page {page_title} with status {status}".format(page_title=page.title, status=
 _(f"Page {page.title} with status {page.status_string}")
 ```
 
+### Translations with templates
+
+You can import `i18n` and then translate with the `translate`/`blocktranslate` template tags. You can also translate string literals passed as arguments to tags and filters by using the familiar `_()` syntax.
+
+```html+django
+{% extends "wagtailadmin/base.html" %}
+{% load i18n %}
+<!-- preliminary lines of code -->
+
+<!-- Do this to use the translate tag. -->
+{% translate "Any string of your choosing" %}
+
+<!-- Do this to use the blocktranslate tag. -->
+{% blocktranslate %}
+    A multi-line translatable literal.
+{% endblocktranslate %}
+
+<!-- Do these to translate string literals passed to tags and filters. -->
+
+{% some_tag _("Any string of your choosing") %}
+{% some_tag arg_of_some_tag=_("Any string of your choosing") %}
+{% some_tag value_of_some_tag|filter=_("Any string of your choosing") value|yesno:_("yes,no") %}
+
+<!-- A typical example of when to use translation of string literals is -->
+{% translate "example with literal" as var_name %}
+{% some_tag arg_of_some_tag=var_name %}
+
+<!-- If the variable is only ever used once, you could do this instead -->
+{% some_tag arg_of_some_tag=_("example with literal") %}
+```
+
+**Note**: In Wagtail code, you might see `trans` and `blocktrans` instead of `translate` and `blocktranslate`.
+This still works fine. `trans` and `blocktrans` were the tags earlier on in Django, but were replaced in [Django 3.1](https://docs.djangoproject.com/en/3.1/topics/i18n/translation/#translate-template-tag).
+
 ## Additional resources
 
 -   [](django:topics/i18n/translation)
 -   A screen-share [Wagtail Space US 2020 Lightning Talk](https://www.youtube.com/watch?v=sLI_AuOMUQw&t=17s) that walks through using Transifex step-by-step
 -   [Core development instructions for syncing Wagtail translations with Transifex](https://github.com/wagtail/wagtail/wiki/Managing-Wagtail-translations)
+-   [Django docs](django:topics/i18n/translation)
diff --git a/docs/releases/5.3.md b/docs/releases/5.3.md
index 5687685611..5fd84c7ed3 100644
--- a/docs/releases/5.3.md
+++ b/docs/releases/5.3.md
@@ -24,7 +24,7 @@ depth: 1
 
 ### Documentation
 
- * ...
+ * Document, for contributors, the use of translate string literals passed as arguments to tags and filters using `_()` within templates (Chiemezuo Akujobi)
 
 ### Maintenance