Paraglide JS is the ideal i18n library for Astro's content-focused sites.

It's a compiler-based i18n library that emits tree-shakable translations, leading to up to 70% smaller i18n bundle sizes compared to runtime based libraries.

• Fully type-safe with IDE autocomplete
• SEO-friendly localized URLs with the i18n routing strategy
• Works with CSR and SSR

Source code

[!NOTE] SSG is not yet supported out of the box. You can integrate Paraglide JS yourself to achieve SSG. PR with an example is welcome.

Setup

1. If you have not initialized Paraglide JS yet, run:

npx @inlang/paraglide-js@latest init

2. Add the vite plugin to the astro.config.mjs file and set output to server:

import { defineConfig } from "astro/config";
+import { paraglideVitePlugin } from "@inlang/paraglide-js";
+import node from "@astrojs/node";

export default defineConfig({
  // ... other
+	vite: {
+		plugins: [
+			paraglideVitePlugin({
+				project: "./project.inlang",
+				outdir: "./src/paraglide",
+			}),
+		],
	},
+  output: "server",
+  adapter: node({ mode: "standalone" }),
});

3. Create or add the paraglide js server middleware to the src/middleware.ts file:

import { paraglideMiddleware } from "./paraglide/server.js";

export const onRequest = defineMiddleware((context, next) => {
+	return paraglideMiddleware(context.request, ({ request }) => next(request));
});

You can read more about about Astro's middleware here.

Usage

import { m } from "./paraglide/messages.js";
import { getLocale, setLocale } from "./paraglide/runtime.js";

// Use messages
m.greeting({ name: "World" }); // "Hello World!"

// Get and set locale
getLocale();    // "en"
setLocale("de"); // switches to German

Learn more about messages, parameters, and locale management →

Disabling AsyncLocalStorage in serverless environments

You can disable async local storage in serverless environments by using the disableAsyncLocalStorage option.

[!WARNING] This is only safe in serverless environments where each request gets its own isolated runtime context. Using it in multi-request server environments could lead to data leakage between concurrent requests.

	vite: {
		plugins: [
			paraglideVitePlugin({
				project: "./project.inlang",
				outdir: "./src/paraglide",
+				disableAsyncLocalStorage: true,
			}),
		],
	},