Opened 12 years ago

Closed 12 years ago

Last modified 12 years ago

#17180 closed Cleanup/optimization (fixed)

Documentation should mention that {% load i18n %} is needed in every template

Reported by: stefan.freyr@… Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords:
Cc: buddy@… Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

The documentation for i18n doesn't explicitly state that the {% load i18n %} statement needs to be put into every template file, even the ones that extend from a template that has already loaded the i18n template tags.

At https://docs.djangoproject.com/en/1.3/topics/i18n/internationalization/

The paragraph:

"Translations in Django templates uses two template tags and a slightly different syntax than in Python code. To give your template access to these tags, put {% load i18n %} toward the top of your template."

Might be extended as:

"Translations in Django templates uses two template tags and a slightly different syntax than in Python code. To give your template access to these tags, put {% load i18n %} toward the top of your template. Note that this needs to be stated in all templates that use translations, even the ones which extend from templates that have already loaded the i18n tags."

Change History (10)

comment:1 by Aymeric Augustin, 12 years ago

Has patch: unset
Triage Stage: UnreviewedAccepted

This looks good to me.

comment:2 by Calvin Spealman, 12 years ago

Should this kind of notice be added to the documentation anywhere any template library is mentioned? I think not. This may be an issue against the template docs, but not against any component which simply uses the templates, any more than every python library needs to specify it has to be imported in every module you want to use it in.

Sort of reminds me of every console video game manual including a couple pages at the start to tell me how to setup my TV, which I should certainly already know by that point. Just my two cents.

comment:3 by Karen Tracey, 12 years ago

I agree with Calvin, there's nothing particular to the i18n tags here. It's documented (https://docs.djangoproject.com/en/1.3/topics/templates/#custom-libraries-and-template-inheritance) that the {% load %}s are not inherited by extending templates. Perhaps that note could be more prominent or earlier in the general template tag documentation, but I don't think we should be adding notes to that effect when discussing each specific template library.

comment:4 by Aymeric Augustin, 12 years ago

I accepted this ticket on the grounds that a little hand-holding can't hurt, and that our docs often have some overlap with related topics.

I don't have strong feelings one way or another; we could mark it as "wontfix" to avoid duplicating information.

comment:5 by Stefán Freyr Stefánsson, 12 years ago

Well, I think the key thing here is what aaugustin mentioned. A little hand-holding can't hurt. If you ask yourself the question who uses the docs, the answer is by and large people who don't know Django all that well. Maybe some people go about learning such frameworks by reading the docs from beginning to end (and remembering every detail) but I for one is not like that. In my case I was using it as a lookup reference because I needed information about the i18n behavior.

In general I subscribe to the DRY principal but I firmly believe that it does not apply as well to documentation, at least not in cases such as this, where there's very little risk of this behavior changing and the docs becoming inconsistent because of it.

comment:6 by Buddy Lindsey <buddy@…>, 12 years ago

Cc: buddy@… added

I submited a pull request for this with the github repository.

https://github.com/django/django/pull/111

Not sure if that was acceptable, but I thought I would at least try.

comment:7 by Buddy Lindsey, 12 years ago

Triage Stage: AcceptedReady for checkin

comment:8 by Aymeric Augustin, 12 years ago

Triage Stage: Ready for checkinAccepted

Please don't mark your own tickets as RFC. They must be reviewed by someone else first.

comment:9 by Tim Graham <timograham@…>, 12 years ago

Resolution: fixed
Status: newclosed

In [514a0013cd38fc586e3b4d8582da2f65c1cdd50c]:

Fixed #17180 - Emphasized the need to load the i18n template tag in each template that uses translations. Thanks stefan.freyr for the suggestion and buddylindsey for the draft patch.

comment:10 by Tim Graham <timograham@…>, 12 years ago

In [232a30804446739602d883e87c3b809c4f99d282]:

[1.4.X] Fixed #17180 - Emphasized the need to load the i18n template tag in each template that uses translations. Thanks stefan.freyr for the suggestion and buddylindsey for the draft patch.

Backport of 514a0013cd from master

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