id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
32356	Add url argument to translate tag	Peter Bittner	nobody	"== Context

Correct translation of extracted text is difficult without appropriate context. That's why Django offers the ""context"" argument to the ""translate"" (former ""trans"") tag and the ""pgettext"" functions, to add a text description to the generated entry in PO files.

However, this is rarely enough. Especially for translators, which often are not developers, a description only is not enough, not even when supported by a file location (file name + line number). A supporting image (e.g. screenshot) or a link to the live (Web) application would yield better translation support.

== Proposal

Hence, we should add a ""url"" argument, in addition to ""context"", to the ""translate"" tag.

The value of the ""url"" should generate a ""#:"" prefixed comment, a reference in PO file terms. See https://www.gnu.org/software/gettext/manual/gettext.html#PO-Files

That value may then be flexibly used by translation tools to their liking (e.g. Rosetta may decide to generate links in their Web UI in the ""Occurrence(s)"" column).

== Examples

{{{
{% translate ""Vote again?"" context ""Polls app tutorial results page"" url ""https://examples.djangoproject.org/polls/1/"" %}
}}}

or

{{{
{% url 'polls:detail' question.id as results_page_path %}

{% translate ""Vote again?"" context ""Polls app tutorial results page"" url results_page_path %}
}}}

would result in

{{{
#: polls/templates/polls/results.html:10
#: https://examples.djangoproject.org/polls/1/
#, fuzzy
msgctxt ""Polls app tutorial results page""
msgid ""Vote again?""
msgstr ""Wieder abstimmen?""
}}}

See Django's polls app tutorial for a development context, e.g.

* https://docs.djangoproject.com/en/stable/intro/tutorial01/
* https://docs.djangoproject.com/en/stable/intro/tutorial03/
* https://docs.djangoproject.com/en/stable/intro/tutorial04/

== Technical notes

For simplicity we may only hold simple text in the ""url"" value. But, as simple text and hard-coded URL paths outdate fairly easily, we may want to use Django's URL resolving features, namely:

{{{
django.shortcuts.resolve_url(to, *args, **kwargs)
}}}

The example above shows a way that may need little technical implementation, and no new concepts to learn. To make the generated URL base value useful this may require passing in or specifying (e.g. in the Django settings) some values used for generation of usable URLs.

== Related source code

 template tag (django.templatetags.i18n):: https://github.com/django/django/blob/master/django/templatetags/i18n.py
 gettext functions (django.utils.module):: https://github.com/django/django/blob/master/django/utils/translation/__init__.py
 management command (django.core.management.commands.makemessages):: https://github.com/django/django/blob/master/django/core/management/commands/makemessages.py
"	New feature	closed	Internationalization	dev	Normal	invalid		Claude Paroz	Unreviewed	0	0	0	0	0	0