๐ช Paraglide JS
Compiler-first i18n for React, TanStack Start, SvelteKit, and any Vite app.
Type-safe message functions, tree-shakable translations, and first-class SSR.
Documentation ยท Quick Start ยท Report Bug
Used in production by
ย ย ย
ย ย ย
ย ย ย
ย ย ย
ย ย ย
ย ย ย
ย ย ย
ย ย ย
ย ย ย
ย ย ย
ย ย ย
Framework-authored and framework-tested
SvelteKit's official i18n integration
TanStack Router's e2e-tested i18n example
Code Preview
// messages/en.json
{
"greeting": "Hello {name}!"
}
// The examples use React. The same m.* API works in SvelteKit, TanStack
// Start, React Router, Vue, Solid, Astro, and vanilla JS/TS โ only the
// surrounding component code changes.
import { m } from "./paraglide/messages.js";
import { locales, setLocale } from "./paraglide/runtime.js";
export function Greeting() {
return (
<>
<h1>{m.greeting({ name: "World" })}</h1> {/* fully typesafe */}
{locales.map((locale) => (
<button key={locale} onClick={() => setLocale(locale)}>
{locale}
</button>
))}
</>
);
}
The compiler turns your messages into typed ESM functions. Modern bundlers can remove unused message functions before they reach the browser. The benchmark compares translated DOM readiness and Brotli transfer against bundled and HTTP-loaded i18next, including scenarios where HTTP i18next transfers fewer bytes. See the build workflow for generated files, Git, CI, and a tree-shaking reproduction.
Why Paraglide?
| Vite-Native | Designed for Vite and modern ESM bundlers. Works with React, TanStack Start, SvelteKit, React Router, Astro, Vue, Solid, and vanilla JS/TS. |
| Production loading | Unused messages can be removed; compare total transfer and active-locale loading in the benchmark. |
| Tree-Shakable | Messages compile to ESM functions, so unused translations are eliminated by your bundler. |
| Fully Typesafe | Autocomplete for message keys and parameters. Typos become compile errors. |
| Built-in i18n Routing | URL-based locale detection and localized paths out of the box. |
| Open Localization Format | Built on inlang: project.inlang/settings.json configures locales, plugins, and file patterns while translations stay in version-controlled files like messages/en.json. |
Get Started With Your Framework
React ยท
Vue ยท
TanStack Start ยท
SvelteKit ยท
React Router ยท
Astro ยท
Vanilla JS/TS
- React + Vite guide โ plain React SPA with the Vite plugin, messages, and a language switcher.
- TanStack Start example โ SSR, localized routing, and TanStack Router integration.
- SvelteKit guide โ SvelteKit's official i18n integration.
- React Router guide โ SSR and client routing.
- Astro guide โ static and server-rendered sites.
- Vite guide โ React, Vue, Solid, or vanilla JS/TS.
[!TIP]
Paraglide is ideal for Vite-based apps. Setup is one plugin, messages compile to ESM, and Vite's tree-shaking eliminates unused translations automatically. Get started โ
React + Vite
Add the Vite plugin, then import message functions and call them โ no provider or context to set up:
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { paraglideVitePlugin } from "@inlang/paraglide-js";
export default defineConfig({
plugins: [
react(),
paraglideVitePlugin({
project: "./project.inlang",
outdir: "./src/paraglide",
emitTsDeclarations: true,
}),
],
});
emitTsDeclarations generates declarations directly and keeps editor types in sync when message files change. No TypeScript installation is required. Set it to false to use JavaScript/JSDoc inference instead.
The Greeting component shown above is all the app code you need. By default, setLocale() updates the selection through your configured strategies and performs a full document navigation: it navigates to the localized URL when URL routing is enabled, or reloads the current document otherwise. The new document renders the app and any document-level locale settings together, with no i18n provider or framework reactivity to wire up.
For the deliberately narrow browser-only setLocale(locale, { reload: false }) escape hatch, see the warning in Basics. It is for a fully client-rendered, non-URL surface that must preserve non-restorable in-memory work and transfers all reactive and document-state updates to the application.
React + Vite setup guide โ ยท Runnable example โ ยท React Router (SSR) guide โ
SSR Ready
Paraglide works in SSR apps with request-scoped locale handling. The server middleware detects the locale from each request and uses AsyncLocalStorage so getLocale() and message functions resolve the right locale even during concurrent requests.
import { paraglideMiddleware } from "./paraglide/server.js";
import { getLocale } from "./paraglide/runtime.js";
import { m } from "./paraglide/messages.js";
export function handle(request: Request) {
return paraglideMiddleware(request, async () => {
const html = `
<html lang="${getLocale()}">
<body>${m.greeting({ name: "Ada" })}</body>
</html>
`;
return new Response(html, {
headers: { "content-type": "text/html" },
});
});
}
SSR Docs โ ยท Middleware Docs โ
Router Composition
Paraglide coexists with your router. Your app keeps canonical routes like /about, while Paraglide maps browser-facing localized URLs like /en/about or /de/ueber to those canonical routes.
Use your framework or router for route definitions, loaders, navigation, and route typing. Use Paraglide for locale detection, localized URL generation, and message functions.
import { deLocalizeUrl, localizeUrl } from "./paraglide/runtime.js";
// Incoming request: localized URL -> canonical app route
deLocalizeUrl("https://example.com/de/ueber").href; // https://example.com/about
// Outgoing link: canonical app route -> localized URL
localizeUrl("https://example.com/about", { locale: "de" }).href; // https://example.com/de/ueber
For routers with rewrite hooks, call deLocalizeUrl() on incoming URLs and localizeUrl() on outgoing URLs. For file-based routers, keep your file routes canonical and localize at the routing boundary.
TanStack Start
TanStack Start uses the same boundary pattern: TanStack Router owns the route tree, loaders, navigation, and typed links. Paraglide handles locale detection, localized URL mapping, and message functions.
import { paraglideMiddleware } from "./paraglide/server.js";
import handler from "@tanstack/react-start/server-entry";
export default {
fetch(req: Request): Promise<Response> {
return paraglideMiddleware(req, () => handler.fetch(req));
},
};
Route code stays TanStack-native: TanStack Router owns route trees, loaders, server functions, navigation, and typed links. TanStack runs Paraglide in e2e tests on every router commit, and the guide covers router rewrites, localized links, prerendering, and SSR behavior.
Quick Start
npx @inlang/paraglide-js init
Coding agents and CI can run init without a terminal UI:
npx @inlang/paraglide-js init --yes --outdir ./src/paraglide --lint eslint
# Or choose --lint oxlint; omit --lint to skip lint setup.
--non-interactive is an alias for --yes. Existing inlang projects are reused, and optional editor recommendations and machine translation are skipped unless explicitly enabled. Dirty git trees require --allow-dirty. Use --no-compile to stage setup before installing dependencies; then run your build. Run init --help for the other options. See optional lint setup.
Stable and production-ready โ @inlang/paraglide-js is on v2 (MIT-licensed), with framework adapters like @inlang/paraglide-js-react at v1.
The CLI sets up everything:
- Creates your message files
- Configures your bundler (Vite, Webpack, etc.)
- Generates typesafe message functions
Then use your messages:
import { m } from "./paraglide/messages.js";
import { setLocale, getLocale } from "./paraglide/runtime.js";
// Use messages (typesafe, with autocomplete)
m.hello_world();
m.greeting({ name: "Ada" });
// Get/set locale
getLocale(); // "en"
setLocale("de"); // loads the German document
Full Getting Started Guide โ
Rich Text
Coming from react-i18next's <Trans>? Use a typed markup adapter โ @inlang/paraglide-js-react (stable, v1) for React, with equivalents for Svelte, Vue, and Solid.
import { ParaglideMessage } from "@inlang/paraglide-js-react";
import { m } from "./paraglide/messages.js";
export function ContactCta() {
return (
<ParaglideMessage
message={m.cta}
markup={{
link: ({ children }) => <a href="/contact">{children}</a>,
strong: ({ children }) => <strong>{children}</strong>,
}}
/>
);
}
The markup names come from your message and are type-checked, so translators control where links and emphasis appear while your React app controls how they render.
Markup Docs โ ยท React ยท Svelte ยท Vue ยท Solid
How It Works
Paraglide compiles an inlang project into tree-shakable message functions. Your bundler eliminates unused messages at build time.
โโโโโโโโโโโโโโโโโโ
โ Inlang Project โ
โโโโโโโโโฌโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Paraglide Compiler โ
โโโโโโโโโโโโโฌโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ./paraglide/messages.js โ
โ ./paraglide/runtime.js โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Watch: How Paraglide JS works in 6 minutes โ
Message Format
Paraglide supports locale-aware formatting via declaration formatters:
plural(Intl.PluralRules) for plural and ordinal categoriesnumber(Intl.NumberFormat) for numbers, currency, compact notation, and moredatetime(Intl.DateTimeFormat) for dates/times with locale-aware outputdate,timeandicu:poundfor ICU MessageFormat 1{d, date},{d, time}and#, see Formattingrelativetime(Intl.RelativeTimeFormat) for values like "yesterday", "in 2 days", or "3 hr. ago"
Gender and custom selects are supported via the variants system.
// Pluralization example
m.items_in_cart({ count: 1 }); // "1 item in cart"
m.items_in_cart({ count: 5 }); // "5 items in cart"
// Works correctly for complex locales (Russian, Arabic, etc.)
Message format is plugin-based: prefer the familiar ICU MessageFormat syntax ({count, plural, one {# item} other {# items}}) via the ICU plugin, keep your existing i18next or JSON files, or use the default inlang format. See message syntax & pluralization.
Formatting Docs โ ยท Pluralization & Variants Docs โ
Why Compiler-First?
Runtime i18n libraries like i18next resolve message keys from dictionaries while your app runs. Paraglide compiles messages into typed ESM functions before your app ships.
Three distinct mechanisms can make translated UI appear sooner:
- Remove unused messages. Static ESM references let bundlers remove message functions your app never calls, reducing code to download and execute.
- Avoid a translation request waterfall. A deferred catalog can require
download app JS โ execute/initialize app โ discover and fetch catalog โ render translated UI. Bundlers discover Paraglide's statically imported messages at build time and can bundle or preload them with app code, removing that runtime catalog-discovery stage. - Ship only the active locale. Opt-in per-locale builds remove other languages from each locale's client graph. Default output retains configured locales for every used message; unused-message tree-shaking alone does not remove inactive locales.
Loading order matters as well as bytes: a smaller catalog can arrive later if its request starts later. Other libraries can also bundle or preload catalogs; compilation alone does not guarantee a faster page. See Don't Lazy-Load Translations for the loading-waterfall rationale.
The published benchmark compares default and per-locale Paraglide with bundled and HTTP-loaded i18next in a client-rendered Vite app. It uses real translations, five routes, one document reload when changing language, and medians of three runs. Complete tables retain default Paraglide's transfer-size losses alongside the per-locale results. Readiness is a translated-content DOM mark, not paint or React rendering time. The measurements do not isolate each mechanism's contribution or establish a ranking against unmeasured libraries.
There is no fixed percentage saving for every app. The build workflow includes a runnable probe that adds unused messages and verifies unchanged production JavaScript hashes.
Comparison
| Feature | Paraglide | Lingui | i18next |
|---|---|---|---|
| Architecture | Compiler-first ESM message functions | Extraction + compiled catalogs | Runtime dictionaries |
| i18n bundle size | Unused message functions removed; see benchmark | Compiled catalogs | Runtime dictionaries |
| Tree-shakable | โ Message functions | Catalog-based | Loading is configured |
| Typesafe | โ Generated message functions | Macro/component workflow | Typed resources and selector API |
| Framework support | TanStack Start, SvelteKit, React Router, Astro, Vue, Solid, vanilla JS/TS | React, Vue, Astro, Svelte, Node.js, vanilla JS | Broad via wrappers |
| Routing + SSR | โ Middleware, request isolation, and URL helpers | Use your framework/router | Use your framework/router |
| Rich text | โ Typed markup adapters | โ Rich-text components | Via framework wrappers |
| ICU MessageFormat 1 | โ Via plugin | โ | Via plugin |
Choose a React i18n library โ ยท Full comparison โ
FAQ
Does Paraglide support ICU MessageFormat?
Yes. Paraglide's message format is plugin-based. You can use the default inlang format, JSON, i18next, XLIFF, or ICU MessageFormat 1 via the ICU plugin.
What about dynamic or CMS-driven keys?
Paraglide works best when message keys are known at build time, because that enables type safety and tree-shaking. For dynamic menus or CMS entries, use explicit mappings from CMS/content IDs to generated message functions, or let the CMS return already-localized content for the active locale. If most translations are only known at runtime, a runtime i18n library may be a better fit.
Can I migrate from i18next?
Yes. Paraglide can compile existing i18next translation files through the i18next plugin, so you can keep your translation format while moving app code from i18next.t("key") to typed message functions over time.
What Developers Say
"Paraglide JS is by far the best option when it comes to internationalization. Nothing better on the market."
Ancient-Background17 ยท Reddit
"Just tried Paraglide JS. This is how i18n should be done! Totally new level of DX."
Patrik Engborg ยท @patrikengborg
"I was messing with various i18n frameworks and must say Paraglide was the smoothest experience. SSG and SSR worked out of the box."
Dalibor Hon ยท Discord
"I migrated from i18next. Paraglide reduced my i18n bundle from 40KB to ~2KB."
Daniel ยท Why I Replaced i18next with Paraglide JS
Blog Posts
- Why I Replaced i18next with Paraglide JS โ A developer's experience reducing bundle size from 40KB to 2KB
- react-i18next Was Fine. Then I Found Paraglide. โ A developer's experience moving from react-i18next to Paraglide
- Inlang / ParaglideJS blew my mind โ A developer's first impressions using Paraglide JS with Remix
Talks
Ecosystem
Paraglide compiles messages from inlang, the open project file format for localization. In concrete terms, project.inlang/settings.json defines your locales, plugins, and translation file patterns; your translations stay as version-controlled files in your repo, such as messages/en.json, locales/en.json, or XLIFF files. Existing formats can be imported/exported through plugins. No account required; inlang tools are optional:
| Tool | Description |
|---|---|
| Sherlock | VS Code extension for inline translation editing |
| CLI | Machine translate and check translations in CI |
| Fink | Translation editor for non-developers |
| Parrot | Manage translations in Figma |
To translate your message files, we recommend General Translation. See Translating messages for setup and other options.
Explore the inlang ecosystem โ
Documentation
- Getting Started
- Framework Guides (React Router, SvelteKit, Astro, etc.)
- Message Syntax & Pluralization
- Formatting (Number/Date/Relative Time)
- Routing & SSR
- API Reference
Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
License
MIT โ see LICENSE
