Creating dynamic routes to internationalization (i) with Astro Build

If you want to read this article in English go here

I recently started learning Astro to create a dashboard-style project.

I really want to implement internationalization (i18n) in this project—the goal is that anyone can use it, regardless of language.

Problem

i18n support in Astro is very good. It works similar to Next.js or any other framework with routing based on file/folder structure.

So, if we want to have a page in English and the same page in Portuguese, we can organize our files like this:

.
└── src/
    └── pages/
        ├── en/
        │   ├── login.astro
        │   └── dashboard.astro
        └── pt-br/
            ├── login.astro
            └── dashboard.astro

And each page has its own i18n strings—cool!

But this is where my problem starts: I don't want to clone all my pages; I just want to change the strings on those pages.

I need something like /[any-language-flag]/all-my-routes.

You may ask, "Why not use something like react-intl?" My answer is that I want to take full advantage of the Astro engine, especially for SSG/SSR, and avoid any client-side components. Generally, these frameworks use React Context, which is rendered only on the client side.

Attempts and Failures

First of all, I read Astro's recipe about i18n and checked out some community libraries to solve this problem.

The first library I tried was astro-i18next, and it looked like exactly what I needed!

Based on an array in the configuration file, astro-i18next generates my i18n pages at build time, so I only need to code once and not worry about cloning pages.

The problem is that astro-i18next appears to be archived or no longer maintained. There are a lot of problems and the last commit was over a year ago.

Solution

After trying other libraries (honorable mention for astro-i18n), I found Paraglide, and it was a game changer for my project.

I chose Paraglide because:

• It's type-safe, so I can use it with TypeScript and take advantage of autocomplete.
• It converts i18n strings to functions, so if a string key changes, my build will fail, catching errors early.
• Using i18n functions allows for better tree shaking, removing unused functions.
• There is a VS Code extension that improves the development experience.

Note: You can use Paraglide in a JS project too, and it also supports Next.js.

After installation and configuration, I used my messages like this:

---
import * as m from "../paraglide/messages.js";
---

<h1>{m.hello({ name: "Alan" })}</h1>

However, this didn't solve my routing problem—I was still cloning my pages for each language I wanted to add.

To resolve this, I changed my project to use dynamic routes in the root route, so all my routes now start with the language flag.

My folder structure looked like this:

.
└── src/
    └── pages/
        └── [lang]/
            ├── login.astro
            └── dashboard.astro

After this change, Paraglide can automatically get the language of the route parameter:

• http://localhost:4321/en/login
• http://localhost:4321/pt-br/login

Now I can add a new language just by configuring it in astro.config.ts and translating my string file.

But I still have two problems to solve:

1. When the user accesses http://localhost:4321/ for the first time without a language flag.
2. If the user changes language on a specific route, I need to keep it on the same route (e.g. /en/create-account should redirect to /pt-br/create-account or /pt-br/criar- account).

Middleware for Language Redirection

To solve the first language redirection problem, I used Astro middleware.

In src/middleware/index.ts, I added this code:

import { defineMiddleware } from 'astro:middleware';
import {
  languageTag,
  setLanguageTag,
  type AvailableLanguageTag,
} from '../paraglide/runtime';

export const onRequest = defineMiddleware((context, next) => {
  // Obter o idioma do parâmetro da URL
  const lang = context.params.lang;

  // Se mudou
  if (lang !== languageTag()) {
    setLanguageTag(lang as AvailableLanguageTag);
    // Redirecionar para o idioma alterado ou padrão (en)
    return context.redirect(`/${lang ?? 'en'}`);
  }

  return next();
});

Language Selector with Current Route

To keep the user on the same route when changing languages, I added this component:

---
import { languageTag } from '../paraglide/runtime';

const pathName = Astro.url.pathname.replace(`/${languageTag()}/`, '');
---

<ul>
  <li>
    <a href={`/pt-br/${pathName}`}>Ir para Português</a>
  </li>
  <li>
    <a href={`/en/${pathName}`}>Go to English</a>
  </li>
</ul>

Additionally, we can translate these messages too, using the second parameter in Paraglide's messages function:

<ul>
  <li>
    <a href={`/pt-br/${pathName}`}>{m.goToLanguage(undefined, { languageTag: 'pt-br' })}</a>
  </li>
  <li>
    <a href={`/en/${pathName}`}>{m.goToLanguage(undefined, { languageTag: 'en' })}</a>
  </li>
</ul>

Considerations

I don't consider my solution to be the best, especially since I'm still learning Astro, so there may be other solutions. If you know of any, please comment, and I'll try :)

Thank you for reading this article! If you have any questions, comment, I'll be happy to answer.

The above is the detailed content of Creating dynamic routes to internationalization (i) with Astro Build. For more information, please follow other related articles on the PHP Chinese website!