Improve documentation for the various date format settings

[Richard]

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.

[Michael]

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:

[Natalia Bidart]

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

[Natalia Bidart]

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?

[Michael]

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!

[Richard]

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.

[Natalia Bidart]

(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...)

[Natalia Bidart]

Accepting for the documentation improvements pending feedback from Claude.

[Natalia Bidart]

Similar report: #35142

[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?

[Claude Paroz]

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.

[Natalia Bidart]

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 .

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

[Natalia Bidart]

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?

[Natalia Bidart]

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

[Rich]

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.

[Lufafa Joshua]

Hey Richard, does this work for you ​PR.

[Rich]

That works for me - thanks Lufafa!

[Sarah Boyce]

Adding the link from #35470 is required

[Sarah Boyce <42296566+sarahboyce@…>]

In 3ac0e432:

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

[Sarah Boyce <42296566+sarahboyce@…>]

In 3d55f296:

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

Backport of 3ac0e43207b4a1b9327ba12612005c285fbff7ee from main.