Opened 4 years ago

Closed 3 years ago

Last modified 3 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 Changed 4 years ago by aaugustin

  • Has patch unset
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

This looks good to me.

comment:2 Changed 4 years ago by calvinspealman

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 Changed 4 years ago by kmtracey

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 Changed 4 years ago by aaugustin

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 Changed 4 years ago by StFS

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 Changed 3 years ago by Buddy Lindsey <buddy@…>

  • 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 Changed 3 years ago by BuddyL

  • Triage Stage changed from Accepted to Ready for checkin

comment:8 Changed 3 years ago by aaugustin

  • Triage Stage changed from Ready for checkin to Accepted

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

comment:9 Changed 3 years ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from new to closed

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 Changed 3 years ago by 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

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