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

[stefan.freyr@…]

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."

[Aymeric Augustin]

This looks good to me.

[Calvin Spealman]

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.

[Karen Tracey]

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.

[Aymeric Augustin]

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.

[Stefán Freyr Stefánsson]

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.

[Buddy Lindsey <buddy@…>]

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.

[Aymeric Augustin]

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

[Tim Graham <timograham@…>]

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.

[Tim Graham <timograham@…>]

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