feat: Strict locale negotiation

[neznaika0]

Description
See #9256
I added a setting for the desired behavior.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value
• Unit testing, with >80% coverage
• Conforms to style guide
• User guide updated

[michalsn]

While this may be a solution for some simpler cases, I think more complex ones won't be so simple.

If we take $supportedLocales as an array of en_US, fr_FR, and the browser is set to fr_BE, the loaded locale will be en_US. Is this the desired result? We can argue about that.

I think in this case changes would be needed to select the fallback locale.

I'm curious what others think about it.

[neznaika0]

If we take $supportedLocales as an array of en_US, fr_FR, and the browser is set to fr_BE, the loaded locale will be en_US. Is this the desired result? We can argue about that.

It current behavior - select first element array

[michalsn]

Yes, I know. While it makes sense when we compare locales loosely. I don't believe it should work that way with strict comparison. Fallback should search for the best match.

[neznaika0]

What would be better than the first (main) element of the array?
EDIT: I note that this is the first change. it's in the Feature settings. It can be transferred to the App when there are user reviews.

[michalsn]

What would be better than the first (main) element of the array?

In the example I presented it would be fr_FR.

We would have to search for the best matching option. It would be fr as a first choice (if available is $supportedLocales) or fr_FR.

[neznaika0]

I tried to add logic to find the nearest locale. But it looks bad.

I added a repeat search for fr if the locale from the request (result best-match) does not start with fr and returned the first fr-BE instead of en-US.

Can I save the first variant?

[michalsn]

How about something like this? Although I haven't tested it yet...

protected function getBestLocaleMatch(array $supported, ?string $header): string
{
    if ($supported === []) {
        throw HTTPException::forEmptySupportedNegotiations();
    }

    if ($header === null || $header === '') {
        return $supported[0];
    }

    $acceptable      = $this->parseHeader($header);
    $fallbackLocales = [];

    foreach ($acceptable as $accept) {
        // if acceptable quality is zero, skip it.
        if ($accept['q'] === 0.0) {
            continue;
        }

        // if acceptable value is "anything", return the first available
        if ($accept['value'] === '*') {
            return $supported[0];
        }

        // look for exact match
        if (in_array($accept['value'], $supported, true)) {
            return $accept['value'];
        }

        // set a fallback locale
        $fallbackLocales[] = strtok($accept['value'], '-');
    }

    foreach ($fallbackLocales as $fallbackLocale) {
        // look for exact match
        if (in_array($fallbackLocale, $supported, true)) {
            return $fallbackLocale;
        }

        // look for locale variants match
        foreach ($supported as $locale) {
            if (str_starts_with($locale, $fallbackLocale . '-')) {
                return $locale;
            }
        }
    }

    return $supported[0];
}

For $supportedLocales set to ['en-US', 'fr-FR'], it will first check for all the options from the Accept-Language header. If no exact match is found, it will check the "general locale": en and then the "locale variant": en-*. The en is just an example, the values will come from the parsed header.

[neznaika0]

I did something similar, but right in the language() method. It seems to me that duplication is not good.

[michalsn]

Oh... I would definitely choose a separate method. Even if some small parts are the same, the main goal is to make it as readable as possible.

[neznaika0]

Ready.

I would pay attention to the description. It is not completely correct. Depends on the array of locales and the query. Sometimes it works, sometimes it returns en instead of en-US. Is the reason for PR. Is there any way to describe it?

CodeIgniter4/user_guide_src/source/outgoing/localization.rst

Lines 34 to 37 in 046967a

	The system is smart enough to fall back to more generic language codes if an exact match
	cannot be found. If the locale code was set to ``en-US`` and we only have language files set up for ``en``
	then those will be used since nothing exists for the more specific ``en-US``. If, however, a language
	directory existed at the **app/Language/en-US** directory then that would be used first.

[neznaika0]

Pff.. Again, my small changes overlap with your additions. 😄

[michalsn]

Pff.. Again, my small changes overlap with your additions. 😄

Yeah, I know - sorry, but I believe this will fit better. I hope I explained my reasons.

[neznaika0]

Ready.

[crustamet]

i am eagerly wating for this update to go trough :D

[michalsn]

The changes are hanging. It looks like GitHub is fighting against this PR 😅

@neznaika0 can you try to rebase?

[neznaika0]

Ok. I'm rebasing last commit again

[michalsn]

Thanks, I spotted two things.

[neznaika0]

Success.

[michalsn]

LGTM - thanks!

[paulbalandan]

Thank you, @neznaika0