Paraglide JS Adapter Astro

Paraglide JS Adapter Astro

An Astro integration for ParaglideJS, providing you with everything you need to internationalize your Astro App

Dead Simple i18n. Typesafe, Small Footprint, SEO-Friendly and with an IDE Integration.


npx @inlang/paraglide-js init
npm i @inlang/paraglide-js-adapter-astro

This will generate messages/{lang}.json files for each of your languages. That's where your translations live.

Register the Integration in astro.config.mjs:

import paraglide from "@inlang/paraglide-js-adapter-astro"

export default {
	// Use astro's i18n routing for deciding which language to use
	i18n: {
		locales: ["en", { code: "de", path: "deutsch" }],
		defaultLocale: "en",

	integrations: [
			// recommended settings
			project: "./project.inlang",
			outdir: "./src/paraglide", //where your files should be


#Adding & using messages

Messages live in messages/{lang}.json files. Add a message to get started

// messages.en.json
	"hello": "Hello {name}!"

You can edit which languages you support in project.inlang/settings.json.

	"languageTags": ["en", "de"],
	"sourceLanguageTag": "en"

Use messages in code by importing from the paraglide/messages.js file generated by the compiler.

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

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

Vite is able to tree-shake the messages. Only messages that are used on an Island will be included in the client bundle. This drastically reduces the bundle size & requires no extra work from you.

#Which language get's used

The integration detects the language from the URL. Simply place your page in a folder named for the language (or the path of the language) & all messages will be in that language.

├── pages
│   ├── en
│   │   ├── index.astro
│   │   └── about.astro
│   └── de
│       ├── index.astro
│       └── about.astro

If a page isn't in a language folder, it will use the default language.

├── pages
│   ├── index.astro // default language
│   ├── about.astro // default language
│   └── de
│       ├── index.astro // de
│       └── about.astro // de

You can configure which languages are available, and which is the default language in project.inlang/settings.json.

To save bundle size the integration doesn't ship language detection code to the client. Instead, it will read the lang attribute on the <html> tag. Make sure it is set correctly.

import { languageTag } from "$paraglide/runtime";

<!doctype html>
<html lang={languageTag()} dir={Astro.locals.paraglide.dir}>
    <slot />

You can also access the current language and text-direction via Astro.locals.paraglide.lang and Astro.locals.paraglide.dir respectively.

For SEO reasons, you should add alternate links to your page's head that point to all translations of the current page. Also include the current page.

	<link rel="alternate" hreflang="en" href="/en/about" />
	<link rel="alternate" hreflang="de" href="/de/ueber-uns" />

Since only you know which pages correspond to each other this can't reliably be done automatically. Add these links manually.


  • Improved Server-Rendering support


Check out an example Astro project with Paraglide integration on StackBlitz