[Django] #32356: Add url argument to translate tag
Django
------------------------------------------------+------------------------
Reporter: Peter Bittner | Owner: nobody
Type: Uncategorized | Status: new
Component: Internationalization | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
== 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 "Found
at" 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 required to pass in or specify (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
--
Ticket URL: <https://code.djangoproject.com/ticket/32356>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Peter Bittner | Owner: nobody
Component: | Version: master
Internationalization |
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Peter Bittner):
* type: Uncategorized => New feature
--
Ticket URL: <https://code.djangoproject.com/ticket/32356#comment:1>
Django
Reporter: Peter Bittner | Owner: nobody
Component: | Version: master
Internationalization |
Severity: Normal | Resolution:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Description changed by Peter Bittner:
Old description:
New description:
== 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
or
would result in
== Technical notes
{{{
django.shortcuts.resolve_url(to, *args, **kwargs)
}}}
== Related source code
--
--
Ticket URL: <https://code.djangoproject.com/ticket/32356#comment:2>
Django
Reporter: Peter Bittner | Owner: nobody
Component: | Version: master
Internationalization |
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak):
* cc: Claude Paroz (added)
* status: new => closed
* resolution: => invalid
Comment:
Thanks for the report, however I don't see a reason for a new argument.
It's already feasible, you can add
[https://docs.djangoproject.com/en/3.1/topics/i18n/translation
/#translator-comments-in-templates Comments for translators in templates],
e.g.
{{{
{% comment Translators: https://examples.djangoproject.org/polls/1/%}
{% translate "Vote again?" context "Polls app tutorial results page" %}
}}}
You can also add a URL to the context, e.g.
{{{
{% translate "Vote again?" context "Polls app tutorial results page, see
https://examples.djangoproject.org/polls/1/" %}
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32356#comment:3>
Django
Reporter: Peter Bittner | Owner: nobody
Component: | Version: master
Internationalization |
Severity: Normal | Resolution: invalid
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Peter Bittner):
Fair enough, adding a comment is nice. But isn't this too generic?
If you know the translation industry a little bit you may be aware that
very few or probably no-one will use the PO files directly. Hence, it's at
the mercy of the translation tool to use the information captured in
''extracted-comments'', ''reference'' and ''flag'' comment fields and the
''msgctxt'' fields.
Also, just to understand the motivation for the comment implementation
better, why would I prefer a "Translators:" prefixed comment over the
dedicated ''msgctxt''? Can you give an example?
The ''reference'' type of comments are already dedicated to referring to
specific locations (namely source file locations, which can easily be
turned into hyper reference links on a Web UI). It would be natural for
tools to extend the linking / link detection to actual URLs coming from
the PO files. We can't assume the same for comments. The nature of
comments is too generic.
--
Ticket URL: <https://code.djangoproject.com/ticket/32356#comment:4>
Django
Reporter: Peter Bittner | Owner: nobody
Component: | Version: master
Internationalization |
Severity: Normal | Resolution: invalid
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Description changed by Peter Bittner:
Old description:
> == 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).
New description:
== 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
or
would result in
== Technical notes
{{{
django.shortcuts.resolve_url(to, *args, **kwargs)
}}}
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
--
--
Ticket URL: <https://code.djangoproject.com/ticket/32356#comment:5>
Django
Reporter: Peter Bittner | Owner: nobody
Component: | Version: master
Internationalization |
Severity: Normal | Resolution: invalid
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak):
> Also, just to understand the motivation for the comment implementation
better, why would I prefer a "Translators:" prefixed comment over the
dedicated ''msgctxt''? Can you give an example?
I've just mentioned two available solution, see #10004 for the motivation.
--
Ticket URL: <https://code.djangoproject.com/ticket/32356#comment:6>
Django
Reporter: Peter Bittner | Owner: nobody
Component: | Version: master
Internationalization |
Severity: Normal | Resolution: invalid
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Claude Paroz):
Replying to [comment:4 Peter Bittner]:
...
> Also, just to understand the motivation for the comment implementation
better, why would I prefer a "Translators:" prefixed comment over the
dedicated ''msgctxt''? Can you give an example?
`msgctxt` is for message disambiguation, that is if you have the "Export"
message once used as a verb and once as a substantive, you should use
`msgctxt` so as languages can translate it differently (it will be
separate entries in the po file). If you don't need that and just want to
provide some translation context to translators, then use translator
comments.
--
Ticket URL: <https://code.djangoproject.com/ticket/32356#comment:7>
Django
Reporter: Peter Bittner | Owner: nobody
Component: | Version: master
Internationalization |
Severity: Normal | Resolution: invalid
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Peter Bittner):
> (it will be separate entries in the po file)
Good. That is the key to using ''msgctxt'' over a comment. Thanks for
clarifying!
But, as I said, the point of this request is to generate a ''reference''
type of comment (`#: `) in the PO file entry. Not an ''extracted-
comments'' type comment (`#. `).
Can developers trigger this as of today?
--
Ticket URL: <https://code.djangoproject.com/ticket/32356#comment:8>