Fixed #35306 -- Updated 5.0 Docs #18028

lufafajoshua · 2024-03-28T10:45:39Z

Trac ticket number

ticket-35306

Branch description

Updated documentation on localization formats usage and precedence.

Checklist

This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period.
I have checked the "Has patch" ticket flag in the Trac system.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
For UI changes, I have attached screenshots in both light and dark modes.

Updated documentation on localization formats usage and precedence.

…5306

nessita · 2024-03-28T17:24:34Z

@lufafajoshua thank you for your work.

When this PR is ready for review, please update the checklist from the PR description, and don't forget to set the proper ticket flags for this to be listed in the branches needing review.

…5306

claudep · 2024-04-13T12:41:09Z

docs/ref/settings.txt

-:doc:`/topics/i18n/index`.
-
-:setting:`USE_I18N` must be active for this setting to have any effect.
+A string representing the fallback language code for this installation.


I don't think we can add fallback here. The paragraph below explains in which case it is used as a fallback language, and when it is the language served to all users.

claudep · 2024-04-13T12:45:06Z

docs/ref/settings.txt


 * If the locale middleware isn't in use, it decides which translation is served
  to all users.
 * If the locale middleware is active, it provides a fallback language in case the
  user's preferred language can't be determined or is not supported by the
  website. It also provides the fallback translation when a translation for a
  given literal doesn't exist for the user's preferred language.
+* If localization is explicitly disabled via the :tfilter:`localize` and
+  :tfilter:`unlocalize` template filters or tags. see
+  :ref:`controlling localization in templates <topic-l10n-templates>`.



This sentence is not complete. However, as a non-native speaker, I'll happily defer choosing a better formulation to someone else.

Yes, "see" needs to be capitalized and it would be good to end with "for [insert something]".
You can just say "for more details" but you might want to be more specific like "for further explanation on [insert something]."
Rough example:

See :ref:`controlling localization in templates <topic-l10n-templates>` for more details.

claudep · 2024-04-13T14:21:01Z

docs/topics/i18n/formatting.txt

@@ -60,6 +60,9 @@ to be machine-readable, you will always want unlocalized values. You
 may also want to use localization in selected templates, rather than
 using localization everywhere.

+The format used is the one from the settings and under normal circumstances
+the locale dictated format has a higher precedence and will be applied instead.


What format? Which settings? Sorry, but I don't think this adds much clarity to these docs.

Maybe something like (once again I'm not a skilled English writer):
When localization is disabled through one of the tag or filter described below, the localization formats used are taken from the general formatting settings (list of settings here?).

Hey @claudep , thanks for your review and response on this, Just for clarity, is it okay to pass a reference to the globalization settings as the general formatting settings instead of listing them.

Good idea for this link! Now that I see that list, maybe it would be nice to distinguish in that list the settings that may overriding by locale formats, and those that don't, and then suggest (maybe in a different PR) separating that list in two sub-lists. Then we would have a perfect section to link to in this PR.

It sounds like we still want to do this, it can be a separate commit or another PR 👍

sarahboyce

Thank you for this @lufafajoshua ⭐ I have a few comments
Can you also update the PR title to better represent what this PR is trying to acheive?

sarahboyce · 2024-05-05T17:06:09Z

docs/ref/settings.txt

-A string representing the language code for this installation. This should be in
-standard :term:`language ID format <language code>`. For example, U.S. English
-is ``"en-us"``. See also the `list of language identifiers`_ and
-:doc:`/topics/i18n/index`.
-
-:setting:`USE_I18N` must be active for this setting to have any effect.
+A string representing the language code for this installation.
+This should be in standard :term:`language ID format <language code>`.
+For example, U.S. English is ``"en-us"``. See also the
+`list of language identifiers`_ and :doc:`/topics/i18n/index`.


This is mostly the same, can you revert the changes to the line length?

sarahboyce · 2024-05-05T17:16:57Z

docs/ref/settings.txt

+* If localization is explicitly disabled via the :tfilter:`localize` and
+  :tfilter:`unlocalize` template filters or tags, it provides fallback
+  localization formats which will be applied instead. see
+  :ref:`controlling localization in templates <topic-l10n-templates>`.


I think as we're referencing explicitly disabling localization, we should reference

:tfilter:`unlocalize`

and

:ttag:`{% localize off %} <localize>`

I think it might be wrong to reference

:tfilter:`localize`

when talking about disabling localization

sarahboyce · 2024-05-05T17:20:56Z

docs/ref/settings.txt


 * If the locale middleware isn't in use, it decides which translation is served
  to all users.
 * If the locale middleware is active, it provides a fallback language in case the
  user's preferred language can't be determined or is not supported by the
  website. It also provides the fallback translation when a translation for a
  given literal doesn't exist for the user's preferred language.
+* If localization is explicitly disabled via the :tfilter:`localize` and
+  :tfilter:`unlocalize` template filters or tags. see
+  :ref:`controlling localization in templates <topic-l10n-templates>`.



Yes, "see" needs to be capitalized and it would be good to end with "for [insert something]".
You can just say "for more details" but you might want to be more specific like "for further explanation on [insert something]."
Rough example:

See :ref:`controlling localization in templates <topic-l10n-templates>` for more details.

sarahboyce · 2024-05-05T17:22:50Z

docs/topics/i18n/formatting.txt

@@ -60,6 +60,9 @@ to be machine-readable, you will always want unlocalized values. You
 may also want to use localization in selected templates, rather than
 using localization everywhere.

+The format used is the one from the settings and under normal circumstances
+the locale dictated format has a higher precedence and will be applied instead.


It sounds like we still want to do this, it can be a separate commit or another PR 👍

sarahboyce · 2024-05-05T17:23:29Z

docs/ref/settings.txt

@@ -3666,6 +3668,9 @@ Forms
 * :setting:`FORM_RENDERER`
 * :setting:`FORMS_URLFIELD_ASSUME_HTTPS`

+
+.. _globalization-settings:


This is a new unused reference, I believe the start of implementing this comment.

lufafajoshua added 2 commits March 28, 2024 12:55

Fixed #35306 -- Updated 5.0 Docs

670045b

Updated documentation on localization formats usage and precedence.

Merge branch 'main' of https://github.com/django/django into ticket_3…

10c3f61

…5306

lufafajoshua added 2 commits April 11, 2024 16:21

Merge branch 'main' of https://github.com/django/django into ticket_3…

7cfee8e

…5306

Modified LANGUAGE_CODE setting in 5.0 docs

c1fa226

claudep requested changes Apr 13, 2024

View reviewed changes

Adjustments to localization format docs 5.0

09ca7d3

sarahboyce reviewed May 5, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fixed #35306 -- Updated 5.0 Docs #18028

Fixed #35306 -- Updated 5.0 Docs #18028

lufafajoshua commented Mar 28, 2024 •

edited

nessita commented Mar 28, 2024

claudep Apr 13, 2024

claudep Apr 13, 2024

sarahboyce May 5, 2024

claudep Apr 13, 2024

lufafajoshua Apr 16, 2024

claudep Apr 16, 2024

sarahboyce May 5, 2024

sarahboyce left a comment

sarahboyce May 5, 2024 •

edited

sarahboyce May 5, 2024

sarahboyce May 5, 2024

sarahboyce May 5, 2024

sarahboyce May 5, 2024

Fixed #35306 -- Updated 5.0 Docs #18028

Are you sure you want to change the base?

Fixed #35306 -- Updated 5.0 Docs #18028

Conversation

lufafajoshua commented Mar 28, 2024 • edited

Trac ticket number

Branch description

Checklist

nessita commented Mar 28, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sarahboyce left a comment

Choose a reason for hiding this comment

sarahboyce May 5, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lufafajoshua commented Mar 28, 2024 •

edited

sarahboyce May 5, 2024 •

edited