FORMAT_MODULE_PATH not acting as I expected.

[Paul Hermans]

I am not certain this is a bug, but may be more of a confusion of a new user (me). Here is what I found:

In my settings:

LANGUAGE_CODE='en-us'
TIME_ZONE = 'America/New_York'
FORMAT_MODULE_PATH = [
    "student_track.formats",
]
USE_L10N=True
USE_I18N = True
USE_TZ = True
USE_THOUSAND_SEPARATOR = True

then in my student_track app:
I had this file:

/formats/en_us/formats.py

but this failed to load (no error message). Eventually I figured out to change the file path to this (Note the Upper Case for the country):

/formats/en_US/formats.py

In my formats.py i still have:

DATE_FORMAT = "M. d, Y"
TIME_FORMAT = "h:i a"

DATETIME_FORMAT = "M. d Y h:i a"
# DATETIME_FORMAT = f"{DATE_FORMAT} {TIME_FORMAT}"


DATE_INPUT_FORMATS = [
    '%m/%d/%Y', '%m/%d/%y', '%Y-%m-%d',  # '2006-10-25', '10/25/2006', '10/25/06'
    '%b %d %Y', '%b %d, %Y',  # 'Oct 25 2006', 'Oct 25, 2006'
    '%d %b %Y', '%d %b, %Y',  # '25 Oct 2006', '25 Oct, 2006'
    '%B %d %Y', '%B %d, %Y',  # 'October 25 2006', 'October 25, 2006'
    '%d %B %Y', '%d %B, %Y',  # '25 October 2006', '25 October, 2006'
]

Template I now have:

<td class="text-start" >{{ record.actual_date }} </td>

and all is working well.

Where I think the issue is that the folder name did not match the language I specified in the settings file and I didn't understand that from the documentation.
When I stepped through the code, it seems that this change occurs in the django.utils.formats.py file when iter_format_modules() is called:

def iter_format_modules(lang, format_module_path=None):
    """Find format modules."""
    if not check_for_language(lang):
        return

    if format_module_path is None:
        format_module_path = settings.FORMAT_MODULE_PATH

    format_locations = []
    if format_module_path:
        if isinstance(format_module_path, str):
            format_module_path = [format_module_path]
        for path in format_module_path:
            format_locations.append(path + ".%s")
    format_locations.append("django.conf.locale.%s")
    locale = to_locale(lang)
    locales = [locale]
    if "_" in locale:
        locales.append(locale.split("_")[0])
    for location in format_locations:
        for loc in locales:
            try:
                yield import_module("%s.formats" % (location % loc))
            except ImportError:
                pass

In my case, this failed with an ImportError, and when I looked into its details, it seems that this line:

    locale = to_locale(lang)

converted had my language specified in settings (en-us) to "en_US".

I don't exactly know why, but it seems intentional. Assuming this is behaving as expected, then it seems that the documentation should be updated to indicate how this works.

I am so new to Django that I am hesitant to propose the actual text that should change, but would be happy to try/help if this seems like the reasonable solution.

[Mariusz Felisiak]

Thanks for the ticket, however this is already ​documented:

"In all cases the name of the directory containing the translation is expected to be named using ​locale name notation. E.g. de, pt_BR, es_AR, etc. "

[Paul Hermans]

Thanks for the reply, and agree that in the locations you mentioned it is stated.

I think that my opinion that the docs are not helpful in this regard is because of a few things
1) I am very new to Django so I have not fought with this issue before.
2) I was under the impression (wrongly) that specifying the format of the date/time had nothing to do with Translation - not because it doesn't make sense, but simply because i wasn't actually trying to translate anything, just control the format(s) of date/times.

You are correct that it is mentioned in the docs where you pointed, but as an inexperienced user it would have been hugely helpful if the section on creating custom formats which suggests using FORMAT_MODULE_PATH in the first place at least made a mention of the importance of the name of that folder, and that it adheres to standard formats for Locale names as specified in the places you already pointed to.

Not a major thing, but it might save people who are not yet experts a lot of grief trying to simply format a date/time.

I appreciate your feedback either way.

[Mariusz Felisiak]

Paul, What do you think about adding the following sentence to the ​FORMAT_MODULE_PATH docs?

The name of the directory containing the format definitions is expected to be named using ​locale name notation, for example `de`, `pt_BR`, `en_US`, etc. "

Would you like to prepare a patch?

[Paul Hermans]

I think that is perfect....maybe a link to the definitions you pointed out to me. I haven't ever done a patch before so have to figure out what that takes. Happy to do it, but it might take a little time.

[Mariusz Felisiak]

Take your time.

[Mariusz Felisiak]

​PR

[Mariusz Felisiak <felisiak.mariusz@…>]

In 9bd849c8:

Fixed #35153 -- Added note about locale name notation to FORMAT_MODULE_PATH docs.

Co-authored-by: Paul Hermans <paul.hermans@…>

[Mariusz Felisiak <felisiak.mariusz@…>]

In e72fdc8:

[5.0.x] Fixed #35153 -- Added note about locale name notation to FORMAT_MODULE_PATH docs.

Co-authored-by: Paul Hermans <paul.hermans@…>

Backport of 9bd849c8d5c587209a231af643a17ec2db802ab2 from main