Creating dynamic route language for i18n in Astro Build

Se quiser ler esse artigo em Portugês clique aqui

Recently, I started learning Astro to create a dashboard-like project.

I really want to implement internationalization (i18n) in this project—the idea is that everyone should be able to use it, regardless of their language.

Problem

Astro’s i18n support is quite good. It works similarly 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—nice!

But here’s where my problem starts: I don't want to clone all my pages; I only want to change the strings on those pages.

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

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

Trying and Failing

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

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

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

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

Solution

After trying other libraries (honorable mention to 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 benefit from autocomplete.
• It converts i18n strings into 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’s a VS Code extension that enhances 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 solve 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 turned into this:

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

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

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

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

But I still have two more issues to solve:

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

Middleware for Language Redirect

To solve the first issue of language redirect, I used Astro middlewares.

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) => {
  // Get lang from url param
  const lang = context.params.lang;

  // If changed
  if (lang !== languageTag()) {
    setLanguageTag(lang as AvailableLanguageTag);
    // Redirect to lang changed or default (en)
    return context.redirect(`/${lang ?? 'en'}`);
  }

  return next();
});

Language Picker with Current Route

To keep the user on the same route when they switch 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 could translate these messages too, using the second parameter in the Paraglide 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>

Example Repository

Here is the example repository with these techniches: https://github.com/alancpazetto/astro-i18n-dynamic

Just clone repository, run install and start project:

git clone https://github.com/alancpazetto/astro-i18n-dynamic
cd astro-i18n-dynamic
npm install
npm start

Open follow URLs to test:

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

Thanks for @gaundergod for the first comment in this article asking for code.

Considerations

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

Thanks for reading this article! If you have any questions, please comment, I’d be happy to reply.

Comments

[Gleb Kotovsky]

Hi! Great Article, thank you for your brevity and clarity. Is there an example or a finished template of what you ended up with?

[Alan Pazetto]

Hi @gaundergod ! Thanks for comment and ask it. I've forgot to create a example repository, but It's available here: github.com/alancpazetto/astro-i18n...

[Gleb Kotovsky]

Grazie, looking forward to your new material in da future