Re: [Django] #35306: Improve documentation for the various date format settings

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* type: Bug => Cleanup/optimization

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:8>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Similar report: #35142
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:9>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------

Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned

Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Lufafa Joshua):

* owner: nobody => Lufafa Joshua
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:10>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Claude Paroz):

Replying to [comment:6 Natalia Bidart]:
> (Another data point: even using `{% localize off %}` does not honor the
settings values. This feels unexpected to me...)

Are you sure? This [https://github.com/claudep/django/commit/57f9982
passing test] seems to show the contrary. Could you double-check?
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:11>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by 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
[https://docs.djangoproject.com/en/stable/topics/i18n/formatting locale-
dictated format] has higher precedence and will be applied instead.
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:12>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Replying to [comment:11 Claude Paroz]:

> Replying to [comment:6 Natalia Bidart]:
> > (Another data point: even using `{% localize off %}` does not honor
the settings values. This feels unexpected to me...)
>
> Are you sure? This [https://github.com/claudep/django/commit/57f9982
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):

{{{#!python
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 .
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:13>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by 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
[https://github.com/django/django/pull/18021 WIP PR].
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:14>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Replying to [comment:14 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
[https://github.com/django/django/pull/18021 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?
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:15>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Lufafa Joshua):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:16>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Richard, could you please take a look at the
[https://github.com/django/django/pull/18028 proposed PR] to confirm if
that helps in terms of documentation improvements?
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:17>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:18>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Lufafa Joshua):

Hey Richard, does this work for you
[https://github.com/django/django/pull/18028 PR].
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:19>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Rich):

That works for me - thanks Lufafa!
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:20>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Claude Paroz):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:21>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Lufafa Joshua):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:22>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:23>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Lufafa Joshua):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:24>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

Comment:

Adding the link from #35470 is required
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:25>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:
Keywords: LANGUAGE_CODE, | Triage Stage: Accepted
DATE_FORMAT |
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Lufafa Joshua):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:26>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution:

Keywords: LANGUAGE_CODE, | Triage Stage: Ready for
DATE_FORMAT | checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:27>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua

Cleanup/optimization | Status: closed
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution: fixed

Keywords: LANGUAGE_CODE, | Triage Stage: Ready for
DATE_FORMAT | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce <42296566+sarahboyce@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"3ac0e43207b4a1b9327ba12612005c285fbff7ee" 3ac0e432]:
{{{#!CommitTicketReference repository=""
revision="3ac0e43207b4a1b9327ba12612005c285fbff7ee"
Fixed #35306 -- Documented fallback localization formats in templates when
localization is disabled.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:28>

[Django]

#35306: Improve documentation for the various date format settings
-------------------------------------+-------------------------------------
Reporter: Richard | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: closed
Component: | Version: 5.0
Internationalization |
Severity: Normal | Resolution: fixed
Keywords: LANGUAGE_CODE, | Triage Stage: Ready for
DATE_FORMAT | checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Sarah Boyce <42296566+sarahboyce@…>):

In [changeset:"3d55f2966d6821fd1fd29d90d1d07c195ae8c2cc" 3d55f296]:
{{{#!CommitTicketReference repository=""
revision="3d55f2966d6821fd1fd29d90d1d07c195ae8c2cc"
[5.1.x] Fixed #35306 -- Documented fallback localization formats in

templates when localization is disabled.

Backport of 3ac0e43207b4a1b9327ba12612005c285fbff7ee from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35306#comment:29>