schmittjoh / JMSI18nRoutingBundle

Allows you to internationalize your routing
http://jmsyst.com/bundles/JMSI18nRoutingBundle
358 stars 159 forks source link

Document the secret "sticky locale" functionality #229

Open gitcerizead opened 5 years ago

gitcerizead commented 5 years ago

Documentation request

This bundle implements a "sticky locale" functionality that is more sophisticated than the example approach given in the Symfony documentation at https://symfony.com/doc/3.4/session/locale_sticky_session.html in that it uses not only a session param called _locale, but also a query string param or cookie called 'hl', and browser lang prefs (via the Accept-Language header).

In my own code, I've commented about this as follows:

    /* NOTE: JMSI18NRoutingBundle has a sophisticated sticky locale
     * implementation for routes for which i18n is disabled, based looking
     * for a query string param or cookie called 'hl', a session param
     * called _locale, and browser lang prefs; so we don't need to manually
     * implement the standard approach described at
     * https://symfony.com/doc/3.4/session/locale_sticky_session.html
     */

Since the sticky locale is only applied on routes for which i18n is disabled (although of course if the user visits an i18n-enabled route the explicit locale from that URL is the value that's made sticky), the appropriate place in the documentation would be http://jmsyst.com/bundles/JMSI18nRoutingBundle/master/usage#leaving-routes-untranslated I think.

gitcerizead commented 5 years ago

It's worth noting, however, that the "stickiness" is achieved solely through the use of a cookie called 'hl', which may be being set in error (i.e. the stickiness feature may be a bug rather than a feature!). See #210 .

But even it's decided to remove the stickiness feature, it would still be good to document how the default locale is determined for a route for which "translation" (i18n) is disabled, as per the description in this ticket.