Astro + Nx + Paraglide - Creating i18n module

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:

• Creating Astro app
• Adding Paraglide in Astro

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.