Opened 4 months ago

Closed 4 weeks ago

Last modified 4 weeks ago

#35306 closed Cleanup/optimization (fixed)

Improve documentation for the various date format settings

Reported by: Richard Owned by: Lufafa Joshua
Component: Internationalization Version: 5.0
Severity: Normal Keywords: LANGUAGE_CODE, DATE_FORMAT
Cc: Richard, Claude Paroz Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

The doc:

https://docs.djangoproject.com/en/5.0/ref/settings/#language-code

specifically states:

"USE_I18N must be active for this setting to have any effect."

This is not true. If USE_I18N is False and a language can not be determined (e.g. the locale middleware is not active), the date template filter will use the value of LANGUAGE_CODE.

I think the handling of date formatting is now very confusing, and the doc for DATE_FORMAT, DATETIME_FORMAT, etc is at best incomplete because it's very difficult to understand when (if ever) these settings are actually used now that the USE_L10N setting has been fully deprecated.

I'm not raising this as a doc issue because I think this system is now somewhat broken. Personally I think that USE_L10N should be brought back; there needs to be a way to turn off localisation of dates (and numbers) separately to translations - they're not the same thing.

I know I can force a particular locale to be used via LANGUAGE_CODE, but I specifically want my format to be used, and the existing DATE_FORMAT, etc settings seems like the right way to do that. I just need a way to force their use, which used to be simply setting USE_L10N = True.

Change History (29)

comment:1 by Michael, 4 months ago

I agree and also miss the USE_L10N setting. Removing it feels like a large tech company that believes they know better than you, and force various changes without asking you to opt in. Unlike linux where it's the same, unless you wish to opt in.

Anyways if USE_L10N is never coming back, we need to deprecate it properly, its still lurking in the code base, grepping to see where its used, with Django 5.0.3 shows:

utils/cache.py|340 col 17| if settings.USE_I18N:
utils/cache.py|420 col 49| is_accept_language_redundant = settings.USE_I18N
utils/translation/trans_null.py|3 col 12| # settings.USE_I18N = False can use this module rather than trans_real.py.
utils/translation/reloader.py|13 col 17| if settings.USE_I18N:
utils/translation/__init__.py|43 col 12| # settings.USE_I18N, as late as possible, so that modules can be imported
utils/translation/__init__.py|54 col 5| USE_I18N will have no effect to which function is served upon request. If
utils/translation/__init__.py|55 col 33| your tests rely on changing USE_I18N, you can delete all the functions
utils/translation/__init__.py|66 col 21| if settings.USE_I18N:
conf/global_settings.py|158 col 1| USE_I18N = True
conf/project_template/project_name/settings.py-tpl|110 col 1| USE_I18N = True
conf/urls/i18n.py|13 col 21| if not settings.USE_I18N:

comment:2 by Natalia Bidart, 4 months ago

Thank you for your comment Michael, though it seems that your may be mixing USE_L10N with USE_I18N?

comment:3 by Natalia Bidart, 4 months ago

Hello Richard, thank you for your report. I've been debugging your issue for a few days now. I think we may need to make some docs adjustments as you imply, but I do not think the code is broken. See as a references this post in stackoverflow.

Have you tried using the formats.py approach to solve your need?

in reply to:  2 comment:4 by Michael, 4 months ago

Replying to Natalia Bidart:

Thank you for your comment Michael, though it seems that your may be mixing USE_L10N with USE_I18N?

Hi Natalia, oh apologies, thank you for clearing that up, cheers!

in reply to:  3 comment:5 by Richard, 4 months ago

Replying to Natalia Bidart:

Have you tried using the formats.py approach to solve your need?

Hi Natalia - I've just tried this and it has worked - thanks! I guess you're right and this can be solved with doc updates.

Personally I would still like the option to just turn this off, i.e. reinstate USE_L10N. You can turn translation off so why not allow localisation to be turned off too? I really don't understand the rationale for removing this setting in the first place.

Best wishes.

comment:6 by Natalia Bidart, 4 months ago

Cc: Claude Paroz added

(Adding Claude as cc.) Claude, do you have any pointers on how to make use of the DATE_FORMAT and related settings? Specifically, how to have them honored in templates.
As an example, I tried using the date template tag, and the settings seem ignored, having the format from LANGUAGE_CODE taking precedence. I know this is mentioned in the docs:

Note that the corresponding locale-dictated format has higher precedence and will be applied instead.

But since LANGUAGE_CODE can not be unset (afaik), it seems unclear when the DATE_FORMAT and related settings are used (outside of the formats.py approach). Just for clarity's sake, I don't think there is a bug in Django, I think we could add some clarifications to the docs to be more explicit about this particular usage.

(Another data point: even using {% localize off %} does not honor the settings values. This feels unexpected to me...)

comment:7 by Natalia Bidart, 4 months ago

Summary: Localisation of dates very confusing - why can't it be turned off anymore?Improve documentation for the various date format settings
Triage Stage: UnreviewedAccepted

Accepting for the documentation improvements pending feedback from Claude.

comment:8 by Natalia Bidart, 4 months ago

Type: BugCleanup/optimization

comment:9 by Natalia Bidart, 4 months ago

Similar report: #35142

comment:10 by Lufafa Joshua, 4 months ago

Owner: changed from nobody to Lufafa Joshua
Status: newassigned

in reply to:  6 ; comment:11 by Claude Paroz, 4 months ago

Replying to Natalia Bidart:

(Another data point: even using {% localize off %} does not honor the settings values. This feels unexpected to me...)

Are you sure? This passing test seems to show the contrary. Could you double-check?

comment:12 by Claude Paroz, 4 months ago

The docs definitely need an update. Something like:

The default formatting to use when localization is disabled, typically with the un/localize template tag/filter. (with a link to https://docs.djangoproject.com/en/stable/topics/i18n/formatting/#controlling-localization-in-templates, which should also states in return that the format used is the one from the settings). In normal circumstances, the locale-dictated format has higher precedence and will be applied instead.

in reply to:  11 comment:13 by Natalia Bidart, 4 months ago

Replying to Claude Paroz:

Replying to Natalia Bidart:

(Another data point: even using {% localize off %} does not honor the settings values. This feels unexpected to me...)

Are you sure? This passing test seems to show the contrary. Could you double-check?

I am sure, but with a caveat :-)
I have double checked and in my manual tests, I was explicitly passing the |date template filter. So, basically, if we add this case to your test (I renamed your original date to my_date for clarity):

        date_plus_tag_template = Template(
            "{% load l10n %}Localized: {{ my_date|date }}. {% localize off %}Unlocalized: "
            "{{ my_date|date }}{% endlocalize %}."
        )

There is this test failure:

AssertionError: 'Localized: 15. Dezember 2024. Unlocalized: 15. Dezember 2024.' != 'Localized: 15. Dezember 2024. Unlocalized: 15-12-2024.'

Using my_date|date:'DATE_FORMAT' also makes the test fails. For example, a valid use case for explicitly wanting to pipe date to a given context provided date would be to truncate a datetime to date .

comment:14 by Claude Paroz, 4 months ago

Ah yes, I missed that! It looks to me as a bug in itself, and maybe merits its own ticket. I transformed my commit as a WIP PR.

in reply to:  14 comment:15 by Natalia Bidart, 4 months ago

Replying to Claude Paroz:

Ah yes, I missed that! It looks to me as a bug in itself, and maybe merits its own ticket. I transformed my commit as a WIP PR.

I agree is a ticket on its own, I created and accepted #35333 providing two tests, one for date and one for time, using subTest. Would you fancy incorporating that in your PR?

comment:16 by Lufafa Joshua, 4 months ago

Has patch: set
Last edited 4 months ago by Lufafa Joshua (previous) (diff)

comment:17 by Natalia Bidart, 4 months ago

Richard, could you please take a look at the proposed PR to confirm if that helps in terms of documentation improvements?

comment:18 by Rich, 4 months ago

The proposed change to the LANGUAGE_CODE setting, in context, reads:

A string representing the language code for this installation. This should be in
standard language ID format. For example, U.S. English
is "en-us", the default format to use when localization is disabled
with localize and unlocalize template filter or tag see
controlling localization in templates
. See also
the list of language identifiers and /topics/i18n/index.

That doesn't read well to me, and also doesn't really cover the situation. I think the first sentence needs to change to make it clear this is a fallback, e.g.:

A string representing the fallback language code for this installation.

The line "USE_I18N must be active for this setting to have any effect." is not true and should be removed I think.

Finally, a third entry could be added to the list of 'purposes', e.g.

If localization is explicitly disabled via the localize and unlocalize template filters or tags. See controlling localization in templates.

The proposed change to formatting.txt seems confusing and unnecessary to me.

comment:19 by Lufafa Joshua, 3 months ago

Hey Richard, does this work for you PR.

comment:20 by Rich, 3 months ago

That works for me - thanks Lufafa!

comment:21 by Claude Paroz, 3 months ago

Patch needs improvement: set

comment:22 by Lufafa Joshua, 3 months ago

Patch needs improvement: unset

comment:23 by Sarah Boyce, 3 months ago

Patch needs improvement: set

comment:24 by Lufafa Joshua, 7 weeks ago

Patch needs improvement: unset

comment:25 by Sarah Boyce, 5 weeks ago

Patch needs improvement: set

Adding the link from #35470 is required

comment:26 by Lufafa Joshua, 4 weeks ago

Patch needs improvement: unset

comment:27 by Sarah Boyce, 4 weeks ago

Triage Stage: AcceptedReady for checkin

comment:28 by Sarah Boyce <42296566+sarahboyce@…>, 4 weeks ago

Resolution: fixed
Status: assignedclosed

In 3ac0e432:

Fixed #35306 -- Documented fallback localization formats in templates when localization is disabled.

comment:29 by Sarah Boyce <42296566+sarahboyce@…>, 4 weeks ago

In 3d55f296:

[5.1.x] Fixed #35306 -- Documented fallback localization formats in templates when localization is disabled.

Backport of 3ac0e43207b4a1b9327ba12612005c285fbff7ee from main.

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