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 %} + + + +{% translate "Any string of your choosing" %} + + +{% blocktranslate %} + A multi-line translatable literal. +{% endblocktranslate %} + + + +{% 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") %} + + +{% translate "example with literal" as var_name %} +{% some_tag arg_of_some_tag=var_name %} + + +{% 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