Opened 11 years ago

Closed 11 years ago

Last modified 11 years ago

#5886 closed (invalid)

documentation of _() syntax in templates is incomplete

Reported by: Dmitri Fedortchenko <zeraien@…> Owned by: nobody
Component: Documentation Version: master
Severity: Keywords: i18n internationalization templates documentation
Cc: Triage Stage: Unreviewed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no


The following syntax is invalid:

{{ _('translate me') }}

This is understandable after one studies the source, however it is not documented.

Not only that, but the documentation is rather limited on the possibility to use _() in templates, only the following is mentioned:
{% some_special_tag _("Page not found") value|yesno:_("yes,no") %}

I feel that the documentation needs to mention the ability to use _() even within {{}}, like this:

{{ _("404 error")|title }}
{{ _("Page not found") }}

I also to feel that either the ability to use single quotes should be fixed, or the documentation should note that this is not supported, since single quotes work in most other areas in the template system.

Attachments (1)

docs_i18n_patch.diff (476 bytes) - added by Dmitri Fedortchenko <zeraien@…> 11 years ago.
Patch to include {{ _() }} syntax in i18n docs.…

Download all attachments as: .zip

Change History (10)

comment:1 Changed 11 years ago by James Bennett

Resolution: invalid
Status: newclosed

The template documentation contains a very clear note at the beginning explaining that the template system is not Python, that arbitrary Python constructs will not work in the template system and that only the specific list of tags, filters and syntax covered in the documentation will work. Additionally, the internationalization documentation (which you have to read to discover how to handle translations in Python code) has a section covering the use of the translation infrastructure in the template system, via the i18n tag library.

comment:2 Changed 11 years ago by Dmitri Fedortchenko <zeraien@…>

I think you misunderstood me, or I am misunderstanding you.

The _() syntax DOES work in Python templates, and it is not a Python construct either.

The internationalization documentation says this:

{% some_special_tag _("Page not found") value|yesno:_("yes,no") %}

However, what the documentation fails to mention is that even {{ _("Translate me") }} works.

It also fails to mention the fact that {{ _('Translate me') }} does not work due to it's single quotes rather then double quotes.
I feel the documentation should note this inconsistency since I am not aware of any area of the documentation which specifically states that double quotes must be used when defining constant strings.

The fact of the matter is that templates now support the _() notation, and the documentation about this is very limited.
I feel that {{_("")}} is better then {% trans "" %} since _() can be used with filters and tags, but despite this fact the new notation is not given much attention in the docs.

comment:3 Changed 11 years ago by Dmitri Fedortchenko <zeraien@…>

Resolution: invalid
Status: closedreopened

comment:4 Changed 11 years ago by Dmitri Fedortchenko <zeraien@…>

Summary: _() syntax in templates only compatible with double-quotes, and the documentation is fuzzydocumentation of _() syntax in templates is incomplete

I changed the title because I realize that it was a little misleading

comment:5 Changed 11 years ago by Gary Wilson

Resolution: invalid
Status: reopenedclosed

Closing for reasons that ubernostrum mentioned. If you want to use translations in templates, please follow:

comment:6 Changed 11 years ago by Dmitri Fedortchenko <zeraien@…>

So if I am supposed to follow the holy bible ( then why does the {{ _() }} method work that is NOT MENTIONED IN THAT URL?

Will that particular feature be broken in the future? Is it just a fluke that it works now?

I guess some clarification would have been nice. Or an actual reading of my ticket...

comment:7 Changed 11 years ago by James Bennett

If that syntax works it should not and should not be relied on (though deliberately breaking it won't necessarily be a high priority). Again, the template documentation makes it clear that the template system is not Python, and that arbitrary Python syntax (such as function calls wrapped in parentheses) should not work and should not be tried. I'm not sure how that can be made clearer aside from drawing up and including a list of every conceivable Python function and every type of syntax people might try. Meanwhile, the i18n docs provide, again, a perfectly clear description of how i18n in templates works.

comment:8 Changed 11 years ago by Dmitri Fedortchenko <zeraien@…>

Ok so {% some_tag _("translate me") %} should work according to the docs, and {{ _("translate me") }} should not work?

Also please concede that there are many functions that work perfectly in django that are not documented and not deprecated, thus my question is perfectly valid.
If it is true that the {{ _("") }} syntax is deprecated, then why is the {% some_tag _("") %} syntax still in the docs?

comment:9 Changed 11 years ago by Dmitri Fedortchenko <zeraien@…>

Has patch: set

I hate to bring this up again, but now Malcolm says that the {{ _("") }} syntax works as an unintended side-effect and says I should send in a docs patch for it?

What gives?

I am sorry to be such a nag about this but it is very important to me since I am writing an app right now and I would like to be sure I am using the correct syntax, it is also important that be able to use filters with my translations so the _() syntax is preferred...

Changed 11 years ago by Dmitri Fedortchenko <zeraien@…>

Attachment: docs_i18n_patch.diff added

Patch to include {{ _() }} syntax in i18n docs....

Note: See TracTickets for help on using tickets.
Back to Top