Basics

Adding and removing locales

To add a new locale, add it to the locales array in <project0name>.inlang/settings.json file.

// project.inlang/settings.json

{
  "baseLocale": "en",
+ "locales": ["en", "de"]
}

Adding and editing messages

Messages are stored in messages/{locale}.json as key-value pairs. You can add parameters with curly braces.

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

Importing messages

After compiling your project, you'll have access to all your messages through the generated messages.js file:

// Import all messages at once
import { m } from "./paraglide/messages.js";

// Use a message
console.log(m.hello_world()); // "Hello World!"

Using parameters

For messages with parameters, simply pass an object with the parameter values:

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

import { m } from "./paraglide/messages.js";

// Pass parameters as an object
console.log(m.greeting({ name: "Samuel" })); // "Hello Samuel!"

Forcing a locale

You can override the locale by passing a locale option as the second parameter:

import { m } from "./paraglide/messages.js";

// Force the message to be in German
console.log(m.greeting({ name: "Samuel" }, { locale: "de" })); // "Hallo Samuel!"

Setting the locale

To change the current locale, use the setLocale function:

import { setLocale } from "./paraglide/runtime.js";

// Change locale to German
setLocale("de");

Disabling reloading

By default, setLocale() triggers a full page reload. This is a deliberate design decision that:

• Enables a small, efficient runtime without complex state management
• Makes Paraglide work in any framework without requiring framework-specific adapters
• Follows the pattern used by major websites like YouTube, as language switching is an infrequent action that doesn't justify the complexity of a no-reload approach

If you need to change the locale without a page reload, you can pass { reload: false } as the second parameter, but then you'll need to handle UI updates yourself.

// Change locale without reloading the page
setLocale("de", { reload: false });

Getting the current locale

To get the current locale, use the getLocale function:

import { getLocale } from "./paraglide/runtime.js";

console.log(getLocale()); // "de"

Routing

The localizeHref function can be used to generate URLs with the current locale:

<a href={localizeHref("/blog")}>Blog</a>

Important: If you route to a different locale, ensure a reload happens afterwards. See https://inlang.com/m/gerre34r/library-inlang-paraglideJs/errors#switching-locales-via-links-doesnt-work

Choosing your strategy

You likely want to use one of the built-in strategies. Visit the strategy documentation to learn more.

Dynamically calling messages

You can dynamically call messages by specifying what messages you expect beforehand. Specifying the messages beforehand preserves tree-shaking.

import { m } from "./paraglide/messages.js";

const messages = {
	greeting: m.greeting,
	goodbye: m.goodbye,
};

let messageKey = "greeting";

console.log(messages[messageKey]());
// "Hello World!"

Advanced usage

• Choosing your strategy
• Server-side rendering
• Multi-tenancy