Add i18n and l10n with lingui and babel

[goanpeca]

Hello, folks!

This PR adds a language switcher and some logic to deal with multiple languages on the xarray website. Using lingui and babel.

Currently, as part of the Scientific Python grant, we have the site 100% translated into Portuguese (Brazilian) and Spanish. Other languages may follow soon - having the infrastructure set up will hopefully help us recruit new translators 😄

We have been working on the automation process for the sync between crowdin and the websites and can help answer any questions you might have.

This PR is a proof of concept and we are happy to adapt to any specific format or needs you might have here. Feedback is appreciated.

Thanks!

Desktop

Mobile

Moving forward

Ensure all translatable strings are wrapped up in the t macro. Yarn build will extract and compile the translations strings

and the rest of the work will happen automatically on https://github.com/Scientific-Python-Translations/xarray-translations and crowding with the volunteer contributors.

For components and pages

import { useLingui } from '@lingui/react/macro'

const Team = () => {
  const { t } = useLingui()
  return ({t`Current core maintainers 🤝`})

For data: convert the object to a function so the t macro can work.

import { useLingui } from '@lingui/react/macro'

export const getLibraries = () => {
  const { t } = useLingui()
  let Libraries = [
    {
      name: 'NumPy',
      description: t`NumPy is the fundamental package for array computing with Python.`,
      url: 'https://numpy.org',
      repo: 'https://github.com/numpy/numpy',
      logo: '/libraries/numpy_logo.svg',
    },
...
}

[vercel]

@goanpeca is attempting to deploy a commit to the xarray Team on Vercel.

A member of the Team first needs to authorize it.

[melissawm]

For context, here's some initial discussion around this topic: pydata/xarray#9094

[goanpeca]

The PR has now selected all localizable strings. I added a simple dropdown but I need some help in getting it to actually change the language.

[goanpeca]

Hi @andersy005 :)

Wanted to know what we could do to help move this forward

Thanks!

[andersy005]

thank you for your patience, @goanpeca! very cool to see this addition to the site! let's remove the RSS feed files (atom.xml, rss.json, rss.xml) from git. these aren't meant to be pushed.

@jhamman, i no longer have permissions to approve the vercel deployment. do you mind authorizing it so we can check how it looks in staging? after that, we can merge to prod.

[goanpeca]

Hi @andersy005 thanks!

Will make the changes and ping you :)

[goanpeca]

thank you for your patience, @goanpeca! very cool to see this addition to the site! let's remove the RSS feed files (atom.xml, rss.json, rss.xml) from git. these aren't meant to be pushed.

I made the updates @andersy005 ! Thanks 🚀

---

cc @jhamman 🙈

[andersy005]

this looks solid, @goanpeca! thank you for putting it together. looking forward to other translations

waiting for @jhamman to authorize the preview, when he gets a moment

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
xarray-dev	❌ Failed (Inspect)			May 8, 2025 3:01pm

[goanpeca]

Thanks @jhamman , there seems to be some issue but I cannot access the logs, any pointers to debug this?

Thanks

[jhamman]

Here are the logs:

[08:00:55.456] Running build in Washington, D.C., USA (East) – iad1
[08:00:55.482] Cloning github.com/xarray-contrib/xarray.dev (Branch: add-i18n, Commit: a89f645)
[08:00:57.628] Cloning completed: 2.146s
[08:01:00.884] Restored build cache from previous deployment (5tdvhbKSYoayVgx2MA7LLnnudq8u)
[08:01:01.928] Running "vercel build"
[08:01:02.351] Vercel CLI 41.7.3
[08:01:05.911] yarn config v1.22.19
[08:01:05.950] success Set "enableGlobalCache" to "false".
[08:01:05.951] Done in 0.04s.
[08:01:05.960] Installing dependencies...
[08:01:06.152] yarn install v1.22.19
[08:01:06.231] [1/4] Resolving packages...
[08:01:21.212] [2/4] Fetching packages...
[08:01:51.677] error @lingui/core@5.3.1: The engine "node" is incompatible with this module. Expected version ">=20.0.0". Got "18.20.6"
[08:01:51.689] error Found incompatible module.
[08:01:51.689] info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.
[08:01:51.753] Error: Command "yarn install" exited with 1
[08:01:52.336] 
[08:01:55.468] Exiting build container

[andersy005]

[08:01:51.677] error @lingui/core@5.3.1: The engine "node" is incompatible with this module. Expected version ">=20.0.0". Got "18.20.6"

@jhamman, can we bump the node version in our vercel settings?

[goanpeca]

Hi @jhamman and @andersy005, wanted to ask if the vercel configuration could be updated 😄 ?

Thanks! 🚀

[jhamman]

I've bumped our node version to 20.x. The (re)deployment ran and reported this error:

 ⨯ ESLint: Invalid Options: - Unknown options: useEslintrc, extensions - 'extensions' has been removed.

@andersy005 - do you have bandwidth this week to help unblock here?

[ianhi]

Hi,

We've moved to netlfiy and now use node version v20.19.5 which runs without error. So I suspect with a rebase and conflict resolution this will work. @goanpeca are you still interested in working on this? I think this is a valuable thing and would like to help see it through.

[melissawm]

I can help push this forward - thanks for the ping!

I am traveling at the moment but can take a look probably around Nov 10. Does that work?

[ianhi]

I am traveling at the moment but can take a look probably around Nov 10. Does that work?

sounds great! I've left a note on my calendar to check back then. Excited to to work to get this in.

[ianhi]

I looked into the broken blog pages in a loop with claude. it came to this conclusion:

The root cause is that src/pages/blog/index.js, src/pages/blog/[id].js, and src/pages/cards/[id].js don't call loadCatalog in their getStaticProps, so pageProps.translation is undefined for those pages. Meanwhile, _app.js unconditionally calls useLinguiInit(pageProps.translation) for every page.

This worked locally because of how useLinguiInit in src/i18n.ts is structured:

• On the client, it only calls i18n.loadAndActivate({ locale, messages }) when !i18n.locale (i.e., the very first page load)
• After visiting any page that does load the catalog (like the homepage), i18n.locale is already set
• Client-side navigation to a blog post skips the loadAndActivate call entirely and silently reuses the already-initialized catalog

On Netlify (or any direct URL access), there's no prior page visit to initialize lingui. The static page tries to call i18n.loadAndActivate with undefined messages — both server-side during pre-rendering and during client hydration — which crashes and produces the 500.

The fix is to add loadCatalog(locale) to getStaticProps in all three files, matching the pattern already in src/pages/index.js:

import { loadCatalog } from '../../i18n'

export async function getStaticProps({ params, locale }) {
  const translation = await loadCatalog(locale)
  // ... existing code ...
  return { props: { /* ...existing props..., */ translation } }
}

[netlify]

✅ Deploy Preview for xarraydev ready!

Name	Link
🔨 Latest commit	39741fe
🔍 Latest deploy log	https://app.netlify.com/projects/xarraydev/deploys/698f930a2ea969000858d7f2
😎 Deploy Preview	https://deploy-preview-772--xarraydev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[melissawm]

I think pretty much there! Thanks for the direction @ianhi - I did it slightly differently just because even with those changes the blog was still trying to serve localized versions of the posts, which I don't think we want anyway.

For disclosure, I did use some AI assistance to figure out some of the errors I didn't know how to fix, but I have reviewed and modified the code myself.

[ianhi]

thank you for sticking with this @melissawm ! fixing these weird kinds of errors is the worst. a great use for AI code assistance. I appreciate the clear statement re usage. Its looking great. Just a few more small issues.

The language picker is still available on teh blog. if you click it the content stays fine, but header gets broken:

in pt the header css might need changeing because a word got longer. not really sure if there is a nice solution here:

not everything is translated. is this because no one translated it, or because it didn't get integrated into the translation site?

[melissawm]

Thanks @ianhi ! I removed the switcher from the blog pages and adjusted the fit on the header - let me know if this is an acceptable solution. Potentially, if translated content is too large we could have problems. I don't really think it'll happen though.

[melissawm]

About the missing translations: Although our dashboard says the site is 100% translated, I believe this work was completed after this initial PR was created. This means after it is merged, we may need a new sync with the crowdin hook.

[ianhi]

Amazing stuff thank you! I checked through the depths of the javascript with claude and found a few minor issues (e.g. the metpy isn't translated because the t is on the wrong side of the backtick. But I think we should fix in a follow up after seeing how sync the new crowdin etc.

[melissawm]

Awesome! Once this is merged, I'll make sure to follow up with any fixes that are necessary. Thank you so much for your patience!