i18n routing

[ematipico]

• Accepted Date: 2022-09-14
• Reference Issues/Discussions: i18n routing #600
• Author: @ematipico
• Champion(s): @ematipico
• Implementation PR:

Summary

First-class support for localized routes, aka i18n routing.

Background & Motivation

Many websites need to ship support for translated/localised websites for many reasons:

• legal;
• localised content;
• localised market;
• etc.

Nowadays there are workarounds in Astro to make it work, although these workarounds have limitations, and because of that many users can't ship their website properly, or they have to work more to compensate the lack of first-class support.

Goals

• Localised routes with locale prefixes;
• Default locale with no prefix;
• Redirect to default locale if prefix enabled;
• Localise injected routes;
• Domain support, with the help of Adapter features, so this will be bound to the limitations of the hosting provider;
• Provide the necessary APIs for integrations and libraries to request information about the current locales;
• Locale detection via the Accept-Language header, so support SSR;
• Provide first-class APIs to users to work around locales (.astro components, endpoints, middleware);

Non-Goals

• Localised data (dates, numbers, plurals, et.c);
• Dictionaries where users can store translations of pre-defined words;
• SEO optimisations;

[SudoCat]

Does this task have someone working on it, or would contributions be welcome?

[ematipico]

Does this task have someone working on it, or would contributions be welcome?

I'll champion it; this means I will manage the project and work on it full-time, but that doesn't mean that third-party contributions aren't welcome. This means that the project will have a boost with a defined release date. You're more than welcome to contribute; we can use Github/Discord as a coordination medium, and I will help with PR reviews and merge them in case there's some delay. Any help is appreciated!

[sasoria]

Awesome! This would make my Astro app a lot simpler 🙌

[SudoCat]

Does this task have someone working on it, or would contributions be welcome?

I'll champion it; this means I will manage the project and work on it full-time, but that doesn't mean that third-party contributions aren't welcome. This means that the project will have a boost with a defined release date. You're more than welcome to contribute; we can use Github/Discord as a coordination medium, and I will help with PR reviews and merge them in case there's some delay. Any help is appreciated!

Excellent! I'm so stoked to see this moving forward, this is going to be a huge help for my clients, and should hopefully help with convincing more people to make the jump to the beautiful astro revolution.

The initial work I did while experimenting on how this could be approached can be found here. I'm not sure how much of it will actually prove useful, as it was a pretty ramshackle approach I threw together, and I have a somewhat limited understanding of the inner working of Astro. I've joined the discord (@sudocat), and I'll be happy to talk through what I can offer, and if there's anything salvageable from my initial investigation.

Once again, super stoked to see this moving forward, thank you for championing it for us all! 🎉

[maddsua]

Interesting, I literally have a module that does most of the mentioned features, including:

• redirects
• alternative pages lists
• SEO alternative tag support
• language-aware links
• external link detection

and probably something else that I'm not remembering rn.

Should I share the code?

[ematipico]

Feel free to do it @maddsua :)

[maddsua]

Feel free to do it @maddsua :)

I'll just do that as gist for now. It's not really a single module at the moment, more like a bunch of stuff that just manages to work well enough

https://gist.github.com/maddsua/45f014ed9d50701b89af48ed6a7795da

[maddsua]

Feel free to do it @maddsua :)

I'll just do that as gist for now. It's not really a single module at the moment, more like a bunch of stuff that just manages to work well enough

https://gist.github.com/maddsua/45f014ed9d50701b89af48ed6a7795da

I like the SSR version of it much more, that why I wasn't happy about Edge adapters being nuked, but let's not talk about it.
What Astro can do right away is to add a piece of code that would detect preferred language based on set cookie, hl search param, user geoinfo or just accept-language header. This info can be provided as a prop of the Astro global object. We should probably add some kind of user-provided language-replacement map, for case when a person want's to get a page in French, but we only have Dutch and English, so by sorting that map we determine that English should be served.

[maddsua]

For SSG mode, we just render all pages based on provided languages.
A map should be created for cases when some pages have different set of languages, and all links should be adapted to it based on user-provided language priority by the same logic as in SSR mode.
To me it does not seem to be any harder than globbing all page endpoints and applying altLanguages to them. Times dynamic paths, that wouldn't be so easy 😬

[jlarmstrongiv]

Hey @ematipico 👋

Nice to see that Astro will treat internationalization as a first class concern 😄 while short-lived, I learned a lot from implementing and maintaining astro-i18n-aut. I’m glad that the official Astro support will also be UI framework agnostic

When you say localized routes, do you mean /about and /es/acerca-de? While it was requested in my library, it’s something I feel can only be implemented in Astro core.

Another request that I implemented was base path support. I didn’t see it listed here, but I assume that i18n routing would respect common config options.

Provide the necessary APIs for integrations and libraries to request information about the current locales;

That’s great! I implemented several helpers to make this easier, but so long as you expose the i18n config, those will all work with minimal changes.

Localise injected routes;

This is great! Will there also be the option to opt-out too?

Redirect to default locale if prefix enabled;

Will the Astro sitemap integration automatically remove those default locale redirects from the final sitemap?

[ematipico]

@jlarmstrongiv

This is great! Will there also be the option to opt-out too?

The idea is that the majority of the features will be opt-in. The default functionalities will have to match the functionalities provided by starlight

Will the Astro sitemap integration automatically remove those default locale redirects from the final sitemap?

I don't have an answer to that because I don't know the integration well. What your take on this one?

[jlarmstrongiv]

@ematipico after more research, while my solution may not be the answer, it does seem that the sitemap integration will need to update its hreflang implementation (with x-default)

When you say localized routes, do you mean /about and /es/acerca-de? While it was jlarmstrongiv/astro-i18n-aut#12 in my library, it’s something I feel can only be implemented in Astro core.

Still curious about that one

[ematipico]

When you say localized routes, do you mean /about and /es/acerca-de? While it was jlarmstrongiv/astro-i18n-aut#12 in my library, it’s something I feel can only be implemented in Astro core.

Still curious about that one

That's something we plan to support, but not as part of the initial implementation. :)

@jlarmstrongiv quick question for you: let's say we have a locale that misses a translated page - e.g. /es/getting-started, what's the expected behaviour from your point of view?

• render /es/getting-started but with the content of the default locale
• doing a redirect to /en/getting-started
• something else?

[SudoCat]

@jlarmstrongiv quick question for you: let's say we have a locale that misses a translated page - e.g. /es/getting-started, what's the expected behaviour from your point of view?

• render /es/getting-started but with the content of the default locale

• doing a redirect to /en/getting-started

• something else?

I think this depends on how the developer is implementing the page. In most cases, you probably just want a regular old 404 as the default, to avoid encountering unpredicted quirks with hreflangs and SEO. For many pages, the page may not be relevant in another language - for example, a product only available in a specific region, or other content pertaining to the country in question.

Fallback content is something that should be managed by the developer - if you're in a SSR context, you could define your own content fallbacks, or the CMS may provide a locale fallback order. In a SSG context, you'd define the behaviour during your getStaticPaths presumably?

[jlarmstrongiv]

That's something we plan to support, but not as part of the initial implementation. :)

I tried to support it in my integration, but it’s extremely difficult to do without it being in the Astro core.

Fallback content is something that should be managed by the developer - if you're in a SSR context, you could define your own content fallbacks, or the CMS may provide a locale fallback order. In a SSG context, you'd define the behaviour during your getStaticPaths presumably?

That’s a great point! Most of the developers who used my integration and made their project public had smaller sites and usually had their local language and English. They always provided all their translations for all their pages. But, I can definitely see that being necessary for large sites spanning many languages.

@jlarmstrongiv quick question for you: let's say we have a locale that misses a translated page - e.g. /es/getting-started, what's the expected behaviour from your point of view?

For my blog site, I’m currently using content collections to manage translations. So, if a content collection is missing a translation (which would happen once I add my wife’s native language), I would expect a temporary redirect to the default locale.

But, for my application site, I’m using FormatJS exclusively. In that case, if just a couple translations are missing or need to be updated, I would render /es/getting-started but with the content of the default locale when missing.

Plus, @SudoCat had great examples with products only available in certain countries.

---

So, I suppose the answer is “it depends”. And if the developer has control of the rendering in an Astro page, it can know which locale its on, and what to do in all those cases:

• Translate the page if it has the translations available
• Redirect to the default locale if it doesn’t have the translations
• Don’t redirect, but provide the default locale when missing translations
• Send a 404, because it’s a region specific page

Except the default locale prefix one /en/about—whether to redirect or 404. For the first implementation, 404 would be easier to avoid having to update the sitemap extension.

[lilnasy]

Can users localize error pages?

[lorenzolewis]

I can't speak to the other libraries mentioned here, but we've been using Starlight extensively for the past several months on https://beta.tauri.app and it's been really nice to use the i18n functionality the way it's built out there.

I'm curious if you're envisioning this to be a solution for any Astro route created by a .astro file, or is this is something that is focused on Content Collections for this proposal?

Super excited to see this one and more than happy to work with it and give some feedback along the way! 🥳

[ElianCodes]

This would indeed make Astro way more interesting for agencies working on content / marketing websites.
excited to see the result!

[ematipico]

RFC Stage 3 now open