Internalization - "User language auto-detection" paragraph misleading

[x7upLime]

I found the part of the internationalization tutorial, that shows how to enable the i18n urls, a little misleading.

Everything before "Adding a language prefix to URLs" seem to work fine (including Enabling the locale management UI (optional)), then in this section there are a couple of paragraphs/comments that leads to believing that adding i18n_patterns() is enough to create the internationalized routes:

To implement this, we can use Django’s built-in i18n_patterns function, which adds a language prefix to all of the URL patterns passed into it. This activates the language code specified in the URL and Wagtail takes this into account when it decides how to route the request.
...

# These will be available under a language code prefix. For example /en/search/

Your URLs will now be prefixed only for the French version of your website, for example:
...

At least in my case (or so I believe..) adding i18n_patterns() was not sufficient to generate the urls themselves, as I confirment with the following snippet:

  {% get_available_languages as languages %}
  <h3>"Available languages.."</h3>
    {% for lang_code, lang_name in languages %}
      {% language lang_code %}
      <p>{{ lang_name }}</p>
    {% endlanguage %}
  {% endfor %}

The output showed all my locales, but there was no correspondence in the urls.

I gave a look to my database:

sqlite> select * from wagtailcore_locale;

Again, all the locales showed, so the issue is not related to the model.

After adding LocaleMiddleware from the section User language auto-detection, the endpoints were responding as expected (/it, /en, /ca, /es, ...)
I thought this section was just to automatically deduct the language from the user's browser and not related to the act of giving the user a switch in the .html to change it themselves, therefore at first I skipped it.

There was this paragraph in particular that confused me:

After wrapping your URL patterns with i18n_patterns, your site will now respond on URL prefixes. But now it won’t respond on the root path.

My claim is that LocaleMiddleware was needed in my setup for the url endpoints to work.

As a support there's the note in Django's translation doc that says:

Make sure you’ve activated translation for your project (the fastest way is to check if MIDDLEWARE includes django.middleware.locale.LocaleMiddleware). If you haven’t yet, see How Django discovers language preference.

and this explanation of how Django discovers the language.

Still some issues on my end

I should also mention that I have some issues in making everything work...
The code snippet mentioned in this section of the same page didn't work to switch page to the translated version.

My workaround looks like this:

  {% if page %}
    {% for translation in page.get_translations.live %}
     {# I prepended "/{{ translation.locale.language_code }}" to the example #}
      <a href="/{{ translation.locale.language_code }}{% pageurl translation %}" rel="alternate" hreflang="{{ translation.locale.language_code }}">
        {{ translation.locale.language_name_local }}
      </a>
    {% endfor %}
  {% endif %}

Pertinent section of the Wagtail docs

• Adding a language prefix to URLs
• User language auto-detection

Details

I would prefer this pages to be clearer and state the necessity of the presence of LocaleMiddleware.

Working on this

If this issue receives enough interest, I would be more than happy to work on it.

[ealvan]

I have same issues to link a page, doesn't change properly the url with the tag {% pageurl %}. When it's a default language everythings works, because I put in i18n() function the parameter prefix_default_language=True,(it means no prefix "/en/"). But, when I link a page in a RichTextField doesn't go to the expected page(goes to 404 error) when it's tranlated. Doesn't show the prefix in the url, the same case as @x7upLime have.