Starlight localization API proposal

[delucis]

This is an initial proposal sketching out a problem space and goals, but not yet landing on a definite solution. Would love feedback on the concept, whether it’s valuable, what would be important to consider, concerns, etc.

Summary

Provide a full localization API out-of-the-box with Starlight, exposing the same tools used to localize Starlight’s built-in UI to developers building pages and components for their own sites.

Background & Motivation

Starlight comes with internationalization (i18n) support for routing and page layout and includes UI translations for a growing number of languages (with new contributions always welcome!)

Internally, Starlight’s UI uses a simple key–value dictionary lookup for the current locale and falls back to a site’s default locale (or, in rare cases, to English if no value is defined for both the current and default locales).

The dictionary looks something like this (abbreviated):

{
  "skipLink.label": "Skip to content",
  "search.label": "Search",
  "search.shortcutLabel": "(Press / to Search)",
  "search.cancelLabel": "Cancel"
}

Our internal API consists of a useTranslations() factory, which returns a t() function:

const locale = 'en';
const t = useTranslations(locale);
const string = t('search.label'); // => 'Search'

It would be useful to users to have access to something like useTranslations() for their own components, especially now that extending Starlight’s default i18n dictionary is supported.

However, exposing our current helper function comes with some issues:

• Starlight’s localization system is intentionally very basic and does not support common l10n requirements like variable interpolation, pluralization, and gendered variants. Building these advanced features ourselves seems unwise, but not including them seems like an invitation for feature requests.

• We currently require passing in the locale but do not expose a helper for quickly getting the current locale, which is not the most user friendly API. Two imports and three function calls would be needed to get a string:

  import { useTranslations, getLocale } from '@astrojs/starlight/imaginary-i18n-module';
  
  const locale = getLocale(Astro.url);
  const t = useTranslations(locale);
  const string = t('key');

  We skirted around this clunkiness by exposing a labels object in overridden component props that already has the localized result of t() for all known keys, but this is static and not available in other components.

Goals

• Allow users to add localized strings to custom components they build.
• Make the user-facing API as simple as possible.
• Support common localization needs.

Example

• In order to access localized strings, users need access to some kind of function that returns these. At its most basic this could look like the not very friendly examples above. Other options could be more powerful, but also more restrictive in where they work. Some examples:

  • An imported helper:

    import { useTranslations } from '@astrojs/starlight/i18n';
    
    const t = useTranslations('en');
    const string = t('key');

    This theoretically works just about anywhere, including on the client, although the client bundle would probably not be optimized at all if this were used in UI components. However, users need to detect the current locale somehow in order to get a t() function, and outside of .astro files, it is unclear how they would do that.

  • A pre-initialized function attached to Astro.locals by a middleware:

    ---
    const string = Astro.locals.t('key');
    ---

    This would allow Starlight to set the current locale for you, but restricts usage to .astro components (and API routes, although those are likely rarely used by Starlight projects).

• If aiming for simplicity, a pre-initialized function may be preferable, even if Astro.locals is still not a broadly familiar API.

• If we are to support more advanced localization needs than simple static string look-up, we should probably defer to a third-party library. Would love to hear from anyone if they have an opinion about i18n tooling, but i18next appears to be the best bet. If we wanted tree-shakeable code for client-side components, Paraglide is interesting, but may be less flexible if we are happy with our existing content collection method of storing/loading user dictionaries, and does not support all common l10n needs yet, including pluralization.

[HiDeoo]

I am very much in favor of this proposal. I think it's a great idea which really addresses a real need.

To share a few thoughts:

• I really like the middleware approach. Even tho it's limited to .astro files, I feel like the helper approach would introduce a lot of complexity and potential overhead just to get access to the translations on the client.
• I have used quite a lot of i18n libraries and my personal conclusion is that for anything more than very basic needs, it often fallbacks to i18next to be the most flexible and powerful solution. It's pretty difficult to compete with their ecosystem and the amount of features they provide.
• Something I would like to consider with this proposal is also plugins. In the original plugin proposal, I mentioned a potential injectTranslations() helper available to plugins. Sharing here for context:

Show original injectTranslations() proposal

With component customization being worked on and some Discord discussions regarding potentially exposing a module using a more advanced version of the existing i18n t() helper (potentially using i18next), I feel like it would be nice to expose a injectTranslations() function to plugins that would allow them to add translations for custom keys (they would be scoped to the plugin name to avoid conflicts).

For example, internationalization support for starlight-blog is something that has already been requested, and instead of dealing with everything that would be required to support it, I think it could be nice to be able to do something like this:

function starlightBlogPlugin() {
  const starlightBlog: StarlightPlugin = {
    name: 'starlight-blog',
    plugin({ injectTranslations, updateConfig }) {
      // Update the Starlight configuration to override various components and use the one provided
      // by the plugin.
      updateConfig({
        // …
      });

      // Add some translations for this plugin.
      injectTranslations({
        en: {
          'sidebar.recentPosts': 'Recent posts',
        },
        fr: {
          'sidebar.recentPosts': 'Articles récents',
        },
      });

      // Return a classic Astro integration that will inject the blog routes.
      return {
        name: 'starlight-blog',
        // …
      };
    },
  };

  return starlightBlog;
}

and in my plugin custom component I could potentially do something like this:

---
import { useTranslations } from '@astrojs/starlight/i18n';

const t = useTranslations(Astro.props.locale);
---

<div>{t('starlight-blog.sidebar.recentPosts')}</div>

[delucis]

Ah great point — I’d forgotten about plugins! 😄

Yes, agreed we should take this into account.

One other plugin-related detail that I didn’t mention above is whether/how plugins could access translation strings. We already have two internal instances where plugin-style code uses the translation system (the asides remark plugin and Expressive Code), which we support via a file system-backed variant of our useTranslations() hook.

This is a bit of a chicken-and-egg situation though: if plugins can injectTranslations() can they also useTranslations()? The main use case would be supporting user customization for strings I guess. And we’d also need to answer how injected translations work along with user-provided ones, i.e. if a user provides a sidebar.recentPosts string, does that take precedence over a sidebar.recentPosts injected by a plugin?

[HiDeoo]

And we’d also need to answer how injected translations work along with user-provided ones, i.e. if a user provides a sidebar.recentPosts string, does that take precedence over a sidebar.recentPosts injected by a plugin?

Regarding this specific point, my first idea was that injected translations would automatically be scoped (using the plugin name) but like you said, this definitely require some more thinking / playing to figure out the exact shape of the feature.

[delucis]

I’m not sure if we’d automatically scope or not, but in my example above I was imagining sidebar.recentPosts to be a key used only by the plugin (e.g. a blog plugin). So it would inject a default set of translations, but users would expect to be able to set their own version of it to override the plugin default or provide an additional language (like they can for Starlight’s strings).

So in that case, injectTranslations() would have to happen before any plugin code needs to useTranslations(). May even be our first case for an additional plugin hook I guess: a provideTranslations() method separate from setup() that we could run first.

[HiDeoo]

Oh I see, I misunderstood your example. Yeah, this may need an additional hook indeed (don't see an alternative yet).

[florian-lefebvre]

Sharing some really quick thoughts

• From my work on https://astro-i18n.netlify.app/, i can tell supporting i18n stuff outside of astro is definitely challenging and may not add much for Starlight: it requires an ALS + a component to serialize data on the client and comes with a few limitations.
• Exposing stuff on locals may provide a better DX, rather than having 2 helpers than depend on each other.
• i18next is powerful and covers most cases, except the ones where you want to interpolate more advanced stuff like links (see Add support for links in translated strings astrolicious/i18n#11)
• You need to think about typings as well. The great thing is that i18next allows to extend them really easily, see https://github.com/astrolicious/i18n/blob/main/package/src/i18next/types.ts)

[florian-lefebvre]

The issue with set:html is when let's say you want to reuse a component, so the link here would be <Link>. Tbh I'm not familiar with how the i18next Trans component works but there are definitely legitimate usecases for it

[delucis]

Ah yeah, I saw i18next supports that with React components. Tricky. Probably not possible for now — maybe something the Container API might unlock?

[florian-lefebvre]

I think using slots.render is enough

[delucis]

Can you do Astro.slots.render('string including <Component />')? I didn’t think so?

[florian-lefebvre]

I think it was not clear enough. This is actually the other way around, see those links:

• https://github.com/yassinedoghri/astro-i18next/blob/beta/README.md#trans-component
• https://github.com/yassinedoghri/astro-i18next/blob/beta/src/components/Trans.astro

[HiDeoo]

Since Starlight v0.28.0, the built-in localization system has been overhauled using the i18next library and available to use anywhere in your documentation website.

See the “Using UI translations” guide to learn more about how to access built-in UI labels or your own custom strings in your project. Plugin authors can also use the new injectTranslations() helper to add or update translation strings.