i18n routing enhancements

[ematipico]

Body

Summary

New enhacements to the i18n routing

Background & Motivation

The current i18n routing misses a few features that users needs and find real use cases. Some other features were pushed back from the original proposal due to time constraints.

Goals

• domain support
• translate 404 and 500 pages
• disable the redirect from / to /<defaultLocale> when prefixDefaultLocale: true is set

[millette]

For point 3, see also #789

[childersd]

Amazing work so far! ✨ Let me chip in with another idea.

I would love to have an i18n API that supports the below set-up:

about.astro
es
└── about.astro

> getAlternateUrl('about.astro', 'en')
'/about'

> getAlternateUrl('about.astro', 'es')
'/es/sobre-nosotros'

This would keep the page structure super clear. It helps with file discoverability and allows multiple contributors to maintain a project without needing to understand all languages. A first step toward this is not assuming that the slug is equal to the filename–which is something that would be nice to have in general.

Having such an API also enables automatically including alternate links with proper hreflang and href attributes in the head. I'll try to something manually for now; achieving the above out of the box would be wonderful.

[millette]

I like this, I think it's really needed.

@childersd Where would the string "sobre-nosotros" reside? Just as a frontmatter slug or somewhere in the astro i18n config? I think the latter would be preferable but I haven't thought it through.

[childersd]

I am also still thinking about this. I guess, inevitably, some user-defined registry is the most straightforward. This gives a complete overview of all paths in a central location. Close to this registry of paths I would also include keys and their translations. Otherwise, you'd end up with i18n snippets defined in files some maintainers may never open. Perhaps a global i18n.ts?

This is actually what I have hacked together for now. Astro could help with compile-time checks on this registry, such as whether each path has an alternative language defined (or explicit redirect to the default) and whether referenced paths actually exist (this would be great for when you're moving files around).

[marekbrze]

I think storing the translated paths directly in the front matters would be the best. This way, after changing the file name, you won't need to also change it in this separate i18n.ts file.

[ematipico]

Yeah that's one of the things I want to implement, but we still lack the infrastructure to do so.

I think this should reside in the configuration:

• this feature must work in multiple situations (middleware, SSR, edge, serverless, etc.), so frontmatter isn't sufficient
• I'm skeptical about introducing another known file in astro

[marekbrze]

Oh yes, you are completely right. I was thinking only about the basic functionality not the whole picture

[jeanlucaslima]

+1 for 404 and 500 page translation. It is a basic feature if you consider user workflow, if you are navigating in a specific language, but go to a page not found you will be sent to the default language.

[millette]

It's moving along: https://astro.build/blog/astro-420/#new-redirecttodefaultlocale-config-option

[fweth]

Hello, I think we often have the situation where we want all locales for a certain page in a single .astro file and only fetch the according data via the Astro.currentLocale parameter. This already works by having a dynamic route folder [locale] for prefixDefaultLocale: true or [...locale] for prefixDefaultLocale: false.

1. I think this could be added to the i18n documentation, since it works fine but was not immedeately obvious to me when reading the docs. Also the routing documentation doesn't mention rest route folders, only rest route files, I think it could be added there as well.
2. Also, but this is optional, in the case where the dynamic route variable is locale and no getStaticPaths() is exported from a route, one could deduce the paths from the i18n settings. But I also see how this would violate the idea that variable names (like locale) carry no semantic information.
3. Not really related to i18n, but I think it would be neat if when no getStaticPaths() is exported from a route following the dynamic part, it looks at the index route right after the dynamic part and uses the export from there (if it exists) or, alternatively, from the closest ancestor which has the export. I think in most cases of dynamic routing, this will reduce boilerplate code. Although, like Chris mentioned on Discord, one can re-export getStaticPaths() from a single file every time, which is definitely an improvement, but still seems boilerplate-y to me.

[ematipico]

That's very interesting. How would a user opt in this feature?

Also the docs about routing don't mention rest route folders, only rest route files, I think it could be added there as well.

I believe dynamic routing was never meant to be used in folders but only for files, that's why docs don't document it.

[fweth]

Hmm, I thought users wouldn't really need to opt in, since if a project is building without errors in the current setting, nothing would change with my proposed feature. It only makes a difference when an error is thrown in the current setting (can't find getStaticPaths()); then, the new feature could, in some situations, infer the static paths. I don't know much about release cycles, but I imagine that this change would be subtle enough to be included in a major release cycle.

Also, I think dynamic folders are incredibly useful, not only for internationalization but especially in this context. It would be so cumbersome to duplicate all pages just to change the locale variable in the data-fetching query... And it works like a charm! If this functionality is not intended, maybe it should be removed altogether; otherwise, it could break in the future.

[fweth]

Another thing I recently ran into, I found no good way to build a language switcher which doesn't route the user back to home. So basically I want to change the locale in the current pathname. I think if there was a stripLocaleFromPathname() function, then we could compose it with getRelativeLocaleUrl() to get the desired result. For this, I think the function computeCurrentLocale() could be rewritten so that it returns not only the current locale but also the path stripped from the computed locale.

[ematipico]

I am not really sure what you're trying to do. Can you explain it with some code? We have getRelativeLocaleUrlList incase you need to have a language switcher, so there's probably some use case that I can't see.

[fweth]

That's what I was looking for, thanks so much!!

[fweth]

Hm, not sure if it really is... The problem is, for getRelativeLocaleUrlList() I need as argument the non-localized pathname (otherwise it creates doubled locales). If the lang switch is e.g. in the header, and I get the pathname from Astro.url, I cannot directly plug it into getRelativeLocaleUrlList(), this is where I thought that stripLocaleFromPathname() would be handy, which I implemented like this:

import { getRelativeLocaleUrl } from "astro:i18n";
const current = Astro.currentLocale;
const stripped = Astro.strippedPathname; // patched the astro package
---
    {
      ["en", "de"].map((lang) => (
        <a
          href={getRelativeLocaleUrl(lang, stripped)}
          class:list={[current === lang && "pointer-events-none underline"]}
        >
          {lang.toUpperCase()}
        </a>
      ))
    }

[jbrodriguez]

Hello, I think we often have the situation where we want all locales for a certain page in a single .astro file and only fetch the according data via the Astro.currentLocale parameter. This already works by having a dynamic route folder [locale] for prefixDefaultLocale: true or [...locale] for prefixDefaultLocale: false.

can you add a simple snippet of how you're doing this ?

i'm localizing my site, but i'd prefer to not duplicate each page in every language, since a structure change would require replicating the change in every folder 🥲

[jbrodriguez]

thanks a lot for this @fweth, i was working in this direction but {lang: undefined} was the last piece in the puzzle !

fwiw, this is how im doing it

pages/[...lang]/somepage.astro

---
import { gsp, useTranslations } from '~/utils/i18n';
import type { Language } from '~/utils/i18n';
...
export const getStaticPaths = gsp;
const { lang } = Astro.params;

const t = useTranslations(lang as Language);
---

gsp defines other languages and uses undefined to render top level default language ('en')
i'm not including 'en' in the list, to avoid generating a duplicated /en pages

export function gsp() {
  return [{ params: { lang: 'es' } }, { params: { lang: undefined } }];
}

useTranslations is based on https://docs.astro.build/en/recipes/i18n/#translate-ui-strings

haven't gotten to the part where i need to implement a language picker yet

[jbrodriguez]

i also "hacked" into the content collection logic, for some text-heavy pages (faq, privacy, etc)

content/privacy/en/global.md

---
title: Privacy
---

This privacy .....

pages/[...lang]/privacy.astro

---
export async function getStaticPaths() {
  const entries = await getCollection('privacy');

  return entries.map((entry) => {
    let lang: string | undefined = entry.id.split('/')[0];
    if (lang === 'en') {
      lang = undefined;
    }
    return {
      params: { slug: entry.slug, lang },
      props: { entry },
    };
  });
}

const { lang } = Astro.params;
const { entry } = Astro.props;
const { Content } = await entry.render();

---

<Content />

not sure that i actually need to pass the slug, it's there at the moment just in case

p.s.: i say "hacked" because i'm not defining any i18n settings in astro.config.mjs

[jbrodriguez]

finally, i implemented the language picker, based on Add I18N Support by reuseman · Pull Request #227 · onwidget/astrowind

BasicScripts.astro

...
  function applyLang(lang) {
    const oldUrl = window.location.href;
    const supportedLangs = locales;

    const urlWithoutOrigin = oldUrl.replace(window.location.origin, '');
    const urlWithoutOriginLang = supportedLangs.reduce((acc, lang) => {
      return acc.replace(`/${lang}`, '');
    }, urlWithoutOrigin);
    const newUrlWithoutTrailingSlash = urlWithoutOriginLang.replace(/\/$/, '');

    const newUrl = `${lang}${newUrlWithoutTrailingSlash}${trailingSlash ? '/' : ''}`;
    // localStorage.lang = lang;
    window.location.pathname = newUrl;
  }

  // const initLang = function () {
  //   console.log('initLang');
  //   const lang = localStorage.lang || '';
  //   applyLang(lang);
  // };
  // initLang();

....

attachEvent('[data-aw-select-language]', 'change', function (_, elem) {
  // hardcoding this here because we don't have access to the i18n functions, i think
  const newLang = elem.value === 'en' ? '' : elem.value;
  applyLang(newLang);
});

i tried to store the chosen language in localstorage and redirect to it on load, but the redirection goes into a loop 😀

[fweth]

Oh wow, astro-i18n-aut looks really nice, will use that as well!

[xanderim]

I have pages/[...lang]/path/to/my/page.astro and then in each page (assuming en is the default locale without prefix):

const lang = Astro.currentLocale;
export function getStaticPaths() {
  return [
    {params: {lang: '/es'}},
    {params: {lang: '/de'}},
    {params: {lang: undefined}},
  ];
}

which is a bit cumbersome but fine with me for now, you could also import the getStatiPaths() function from some common util file... Then use the lang variable in your data fetching logic.

It should be added to the docs

[eric-burel]

Hi, just to keep track of other dicussions: my main request for i18n is to have full-control over the redirections at request-time, while keeping the page static. This would be currently solved using an edge middleware, in the Vercel sense of the term, so not an Astro middleware as currently documented that runs only for dynamically rendered pages at request-time but only at build-time for static pages. I would need a middleware that runs also for static pages. I'd be eager to see something more built-in in this area.

[ArmandPhilippot]

I think it is also missing a way to translate the remarkRehype options depending on the current route.

Right now if the website uses a single locale, we can translate the footnote labels like this:

export default defineConfig({
  i18n: {
    defaultLocale: 'fr',
  },
  markdown: {
    remarkRehype: {
      footnoteLabel: 'Notes de bas de page',
    },
  },
});

But how to handle the translation when the website is multilingual?

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },
  markdown: {
    remarkRehype: {
      footnoteLabel: "???",
    },
  },
});

A possible solution:

• the footnoteLabel should accept a string or a function that receives the current locale as parameter and that returns a string,
• the footnoteBackLabel should include the current locale in FootnoteBackLabelTemplate type,
• the footnoteBackContent should include the current locale in FootnoteBackContentTemplate type.

Right now, it seems the only way to translate the footnote labels depending on the current locale is to use placeholders in the configuration file and a rehype plugin. In that plugin we need to parse the path from history in the vfile parameter to retrieve the locale then to replace the nodes using that locale. It seems doable but it is not ideal.