Provide i18n utilities that can be used on the client

[delucis]

Body

Summary

Astro’s astro:i18n module provides a number of utilities for working with localized URLs, but is intended for server use only. This proposal discusses adding a way to use these from the client.

Background & Motivation

Astro’s utilities like getRelativeLocaleUrl() or getPathByLocale() help work with URLs in sites using i18n but aren’t officially available on the client. Some users have been importing astro:i18n from browser code, but this is risky for a number of reasons:

• The module includes a lot of server-side code. If we’re lucky these might get tree-shaken out, but there’s no guarantee, and there have already been bugs where server code causes issues for people.
• Astro supports a manual “bring your own middleware” i18n strategy. This relies on side effects currently (example), but these can’t be reflected to the client bundle, so using astro:i18n on the client in sites with manual i18n configs will mean the utilities don’t behave correctly.

Goals

• Support astro:i18n on the client to support use cases like language switcher components.
• It would not export APIs that only make sense on the server (e.g. the redirect APIs)

Example

Existing APIs and usage should be possible

Challenges

This would require a significant refactor of the i18n feature and likely a breaking change to the manual i18n option to move away from the current side-effect-powered implementation.

Note

We need more user feedback and information to know what the common use cases are and whether the effort would be justified. Comment below!

[ematipico]

I think all utilities that work on locales and URLs can be ported on the client too.

[delucis]

The issue is currently they rely on some variables that are mutated dynamically when users use middleware(). But that wouldn’t happen on the client. So we’d need to refactor the manual routing approach I think. But yeah, I think it could be possible with some work and a breaking change to how to do manual routing.

[JoostKersjes]

Thanks for opening this discussion @delucis!

We built a static marketing website (https://awareways.com/en/) with 2 languages. There are a couple client-side interactions (e.g. the navigation menu) but no server-side code running through Astro, just the SSG. The only function we are currently using from astro:i18n is getRelativeLocaleUrl.

I followed the add i18n features guide and adapted some of the code examples to fit our needs. Here is our utility that wraps getRelativeLocaleUrl:

type LocaleCode = "en" | "nl";
export function useTranslatedPath(lang: LocaleCode) {
  return function translatePath(path: string, l: LocaleCode = lang) {
    const route = path.replaceAll("/", "");
    const hasTranslation =
      defaultLang !== l &&
      routes[l] !== undefined &&
      routes[l][route] !== undefined;
    const translatedPath = hasTranslation ? routes[l][route] : path;

    const [pathname, hash] = translatedPath.split("#");
    if (hash) return `${getRelativeLocaleUrl(l, pathname)}#${hash}`;

    return getRelativeLocaleUrl(l, pathname);
  };
}

For consistency, we use this utility for all anchors in the website. The key difference is that our LanguagePicker is a Vue component, meaning the code from useTranslatedPath runs on the client.

Taking a step back, all we really need getRelativeLocaleUrl to do is the following:

• Ensure the url complies with our configuration, namely prefixDefaultLocale and trailingSlash
• Run at compile-time, so anchors in the HTML output get a static href value as much as possible
• Work in both client and server code, so that we can create a link using the same function no matter the context

There are probably a handful of ways for us to work around this problem. We could move all the translatePath calls out of our Vue components and pass them down through props, or we could maybe build our own version of getRelativeLocaleUrl that hardcodes our configuration values.

Working with Astro has been an absolute pleasure so far, but astro:i18n feels a bit more clunky than e.g. astro:assets. Don't get me wrong, it is still great to use, but my expectation was that Astro would be far more opinionated about how developers handle translating links and routes in their projects.