DEV Community: Alan Pazetto

Astro + Nx + Paraglide - Creating i18n module

Alan Pazetto — Wed, 21 Aug 2024 12:23:40 +0000

As I told in this my other article, I'm learning Astro.build.

And one of things that I don't like in the integration with Astro and Paraglide is keep all things in /src folder.

In case that you have a large codebase, it could be a problem to manage and keep code clean in future. Okay, I know that Astro can manage very well large codebase in final bundle, but the developer experience isn't very well to put all files together.

I'm very familiar with monorepos and specially with Nx, I've working in another projects, small and very large projects, and Nx really helps to organize code by splitting in modules/libs.

The idea in this article is share how to integrate Astro with Nx and create an i18n module to centralize all messages and paraglide things in one module.

Creating repo

First of all we need to create our start repository.

Just to skip Astro and Paraglide setup, I will start from my last article repository: https://github.com/alancpazetto/astro-i18n-dynamic

So, to use it, 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

If you want to start from scratch, you can follow these nice articles:

Adding Nx

Before we continue to 18n module, we need to setup Nx.

This is simple, Nx has the init command that helps to init Nx workspace in an existing code, so just run this:



npx nx@latest init

When Nx command ask for cacheable script, you can select build and setup folder to ./dist (it could be changed in future)

Feel free to select any other option that command show, this won't impact in this tutorial.

Adding i18n module

If you already uses Nx, you are familiar with Nx Plugins, but if not I will introduce you.

Nx uses a plugin architecture, which you can add or remove a plugin to add or remove features in your workspace.

These plugins can add generators, executors or any other Nx feature.

In our case, we need to create a JS library module, so we will need to plugin JS plugin, called @nx/js.

You can find all Nx Plugins here: https://nx.dev/plugin-registry

So, lets install JS Plugin, by running below command:



npm install -D @nx/js

As installed we can generate our i18n module.

Here I would like to make a recommendation, I really like to use command line tools, however Nx has a nice VSCode Extension that make all generators visually (there are other feature too). So I highly recommend to install this.

But if you doesn't want to use extension or don't use VSCode, no problem, we can run this in terminal:



npx nx generate @nx/js:library --name=i18n --bundler=swc --directory=libs/i18n --importPath=@astro-nx-paraglide/i18n --projectNameAndRootFormat=as-provided --unitTestRunner=none --no-interactive

This will create a module as JS Library using JS plugin, inside libs/i18n path with import path @astro-nx-paraglide/i18n.

You can change to your configs here.

If you want to use VSCode extension, open command palette, search for Nx generate (ui) and select @nx/js:library, add these information in new window:

Meeting i18n module

New module will be created inside libs/i18n, and basically it's a JS library, with index.ts as entrypoint and lib folder that could add all library code.

Setup Paraglide to i18n module

To configure Paraglide in our i18n module, we need to change some things in Paraglide config.

First of all, open your Astro config (like astro.config.mjs) and change paraglide integration outdir:



import { defineConfig } from 'astro/config';
import paraglide from '@inlang/paraglide-astro';

export default defineConfig({
  // Use astro's i18n routing for deciding which language to use
  i18n: {
    locales: ['en', 'pt-br'],
    defaultLocale: 'en',
  },
  output: 'server',
  integrations: [
    paraglide({
      // recommended settings
      project: './project.inlang',
      outdir: './libs/i18n/src/paraglide', // <=== HERE
    }),
  ],
});

It will setup Astro + Paraglide to looks inside this folder (in code we will import in other way).

We need to setup package.json scripts changing paraglide output dir in build time (build and postinstall script):



{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "paraglide-js compile --project ./project.inlang --outdir ./libs/i18n/src/paraglide && astro check && astro build",
    "preview": "astro preview",
    "astro": "astro",
    "postinstall": "paraglide-js compile --project ./project.inlang --outdir ./libs/i18n/src/paraglide"
  },
}

Now we can rerun postinstall script to regenerate paraglide folder: npm run postinstall

After all we have this folder strucuture:

Now we need to export to all code generated paragrlide files.

Paraglide exports 2 folders:

messages.js: that contains all translated message functions
runtime.js: that contains all runtime function, like which language is setted

So we need to edit library entrypoint (index.ts) to export these files:



export * as messages from './paraglide/messages';
export * as runtime from './paraglide/runtime';

Note: By default Nx setup project "verbatimModuleSyntax": true in tsconfig.json and it cause an erro in i18n module, but you can configure your library tsconfig.json to disable this by editing libs/i18n/tsconfig.json adding "verbatimModuleSyntax": false inside compilerOptions.

By now, we don't need libs/i18n/src/lib folder anymore, just delete it.

Integration Astro app with i18n module

Now it's time to integrate all our code.

If you check ./tsconfig.json, a new compilerOptions.path was added by Nx with importPath informed previously appoint to our library entrypoint.

Note: if you get an import error here, you need to setup compilerOptions.baseUrl to ./.

So to integrate our code with module we'll use this import path in our code:



import { messages, runtime } from '@astro-nx-paraglide/i18n';

In our application files, inside src we need to change all imports from ../paraglide/messages (or runtime) to new import path.

For example in src/components/LanguagePicker.astro:



---
import * as m from '../paraglide/messages';
- import { languageTag } from '../paraglide/runtime';
+ import { runtime } from '@astro-nx-paraglide/i18n';

- const makeUrlForLanguage = (lang: string) => `/${lang}${Astro.url.pathname.replace(`/${languageTag()}`, '')}`;
+ const makeUrlForLanguage = (lang: string) => `/${lang}${Astro.url.pathname.replace(`/${runtime.languageTag()}`, '')}`;
---

And inside our pages, like src/pages/index.astro:



---
import Layout from '../layouts/Layout.astro';
- import * as m from '../paraglide/messages';
- import { languageTag } from '../paraglide/runtime';
+ import { messages as m, runtime } from '@astro-nx-paraglide/i18n';
---

<Layout title={m.homePageTitle()}>
  <h1>{m.homePageHeading()}</h1>
-  <p>{m.homePageContent({ languageTag: languageTag() })}</p>
+  <p>{m.homePageContent({ languageTag: runtime.languageTag() })}</p>
</Layout>

Cleanning src folder

As module was setted and all imports changed, we can delete the src/paraglide folder, as we don't use it anymore.

Example repository

Here is the example repository: https://github.com/alancpazetto/astro-nx-paraglide

Just clone repository, run install and start project:



git clone https://github.com/alancpazetto/astro-nx-paraglide
cd astro-nx-paraglide
npm install
npm start

Thanks to read and don't forget to give a heat in this article if you like and leave a comment.

Criando rotas dinâmicas para internacionalização (i18n) com Astro Build

Alan Pazetto — Sat, 17 Aug 2024 14:42:40 +0000

If you want read this article in English go here

Recentemente, comecei a aprender Astro para criar um projeto no estilo de dashboard.

Eu realmente quero implementar a internacionalização (i18n) neste projeto—o objetivo é que qualquer pessoa possa usá-lo, independentemente do idioma.

Problema

O suporte a i18n no Astro é muito bom. Ele funciona de maneira semelhante ao Next.js ou qualquer outro framework com roteamento baseado na estrutura de arquivos/pastas.

Então, se quisermos ter uma página em inglês e a mesma página em português, podemos organizar nossos arquivos assim:

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

E cada página tem suas próprias strings i18n—legal!

Mas é aqui que meu problema começa: eu não quero clonar todas as minhas páginas; eu só quero mudar as strings nessas páginas.

Eu preciso de algo como /[qualquer-bandeira-de-idioma]/todas-as-minhas-rotas.

Você pode perguntar: "Por que não usar algo como react-intl?" Minha resposta é que eu quero aproveitar ao máximo o mecanismo do Astro, especialmente para SSG/SSR, e evitar quaisquer componentes do lado do cliente. Geralmente, esses frameworks usam React Context, que é renderizado apenas no lado do cliente.

Tentativas e Fracassos

Primeiro de tudo, eu li a receita do Astro sobre i18n e conferi algumas bibliotecas da comunidade para resolver esse problema.

A primeira biblioteca que testei foi a astro-i18next, e parecia exatamente o que eu precisava!

Com base em um array no arquivo de configuração, o astro-i18next gera minhas páginas i18n no momento da build, então eu só preciso codificar uma vez e não me preocupar em clonar páginas.

O problema é que o astro-i18next parece estar arquivado ou não ser mais mantido. Há muitos problemas e o último commit foi há mais de um ano.

Solução

Depois de tentar outras bibliotecas (menção honrosa para astro-i18n), encontrei o Paraglide, e ele foi um divisor de águas para o meu projeto.

Escolhi o Paraglide porque:

Ele é seguro por tipo, então eu posso usá-lo com TypeScript e aproveitar o autocomplete.
Ele converte strings i18n em funções, então se uma chave de string mudar, minha build falhará, capturando erros cedo.
Usar funções i18n permite uma melhor tree shaking, removendo funções não utilizadas.
Existe uma extensão do VS Code que melhora a experiência de desenvolvimento.

Nota: Você pode usar o Paraglide em um projeto JS também, e ele também suporta Next.js.

Após a instalação e configuração, usei minhas mensagens assim:

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

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

No entanto, isso não resolveu meu problema de roteamento—eu ainda estava clonando minhas páginas para cada idioma que queria adicionar.

Para resolver isso, mudei meu projeto para usar rotas dinâmicas na rota raiz, então todas as minhas rotas agora começam com a bandeira do idioma.

Minha estrutura de pastas ficou assim:

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

Depois dessa mudança, o Paraglide pode obter automaticamente o idioma do parâmetro da rota:

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

Agora, posso adicionar um novo idioma apenas configurando-o em astro.config.ts e traduzindo meu arquivo de strings.

Mas ainda tenho dois problemas para resolver:

Quando o usuário acessa http://localhost:4321/ pela primeira vez sem uma bandeira de idioma.
Se o usuário mudar o idioma em uma rota específica, preciso mantê-lo na mesma rota (por exemplo, /en/create-account deve redirecionar para /pt-br/create-account ou /pt-br/criar-conta).

Middleware para Redirecionamento de Idioma

Para resolver o primeiro problema de redirecionamento de idioma, usei middlewares do Astro.

Em src/middleware/index.ts, adicionei este código:

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();
});

Seletor de Idioma com Rota Atual

Para manter o usuário na mesma rota ao mudar de idioma, adicionei este componente:

---
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>

Além disso, podemos traduzir essas mensagens também, usando o segundo parâmetro na função de mensagens do Paraglide:

<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>

Repositório de Exemplo

Aqui esta o repositório com as técnicas aplicadas no artigo https://github.com/alancpazetto/astro-i18n-dynamic

Só fazer o clone do repositório, instalar as dependências e iniciar:

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

Depois de iniciado, basta abrir essas URLs no navegador:

Considerações

Não considero minha solução a melhor, especialmente porque ainda estou aprendendo Astro, então pode haver outras soluções. Se você souber de alguma, por favor comente, e eu tentarei :)

Obrigado por ler este artigo! Se você tiver alguma dúvida, comente, ficarei feliz em responder.

Creating dynamic route language for i18n in Astro Build

Alan Pazetto — Sat, 17 Aug 2024 14:35:47 +0000

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:

When the user first accesses http://localhost:4321/ without a language flag.
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:

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.