Paraglide JS

https://paraglidejs.com/
Admin
Paraglide JS is an internationalization library for JavaScript applications, providing comprehensive...
Tokens:73,047
Snippets:896
Trust Score:3.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install i18next Plugin in project.inlang/settings.json

Source: https://paraglidejs.com/file-formats

Configuration example for installing the i18next plugin by adding its URL to the `modules` array in `project.inlang/settings.json`.

```json
{
  "baseLocale": "en",
  "locales": ["en", "de"],
  "modules": [
-    "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@4.4.0/dist/index.js"
+    "https://cdn.jsdelivr.net/npm/@inlang/plugin-i18next@6.0.11/dist/index.js"
  ]
}
```

--------------------------------

### Start a New TanStack Router Project with Paraglide

Source: https://paraglidejs.com/tanstack-start

Use this command to initialize a new project based on the TanStack router example that includes Paraglide JS integration.

```bash
npx gitpick TanStack/router/tree/main/examples/react/start-i18n-paraglide start-i18n-paraglide
```

--------------------------------

### Install `@inlang/sdk` for Lower-level API

Source: https://paraglidejs.com/compiling-messages

Install the `@inlang/sdk` package to use the lower-level `compileProject` API for advanced control over output.

```bash
npm install @inlang/sdk
```

--------------------------------

### JSDoc example for paraglideMiddleware()

Source: https://paraglidejs.com/changelog

Example demonstrating when to use the original request vs the modified request within paraglideMiddleware().

```javascript
/**
 * @type {import('@sveltejs/kit').Handle}
 */
export const handle = async ({ event, resolve }) => {
  const response = await paraglideMiddleware({
    event,
    // Use the original request when the locale is not set in the URL
    // This is useful for frameworks that handle URL localization themselves
    // (e.g. TanStack Router)
    request: event.request,
  });

  return resolve(response.resolved);
};

```

--------------------------------

### Simple JSON Format Example (en.json)

Source: https://paraglidejs.com/file-formats

Basic JSON translation file example for simple key-value pairs.

```json
{
	"greeting": "Hello!",
	"goodbye": "Goodbye!"
}
```

--------------------------------

### Full-Stack User Preference Strategy Example

Source: https://paraglidejs.com/strategy

A comprehensive example demonstrating both client-side and server-side user preference strategies with asynchronous database support. The client strategy handles memory cache and URL query parameters, while the server strategy performs async database lookups.

```javascript
// File: src/locale-strategies.js
import {
	defineCustomClientStrategy,
	defineCustomServerStrategy,
} from "./paraglide/runtime.js";
import {
	getUserLocale,
	setUserLocale,
	extractUserIdFromRequest,
} from "./services/userService.js";

// Client-side strategy - works with user preferences in browser
defineCustomClientStrategy("custom-userPreference", {
	getLocale: () => {
		// Get from memory cache, framework state store, or return undefined to fall back
		return window.__userLocale ?? undefined;
	},
	setLocale: async (locale) => {
		try {
			// Update user preference in database via API
			await setUserLocale(locale);
			window.__userLocale = locale;

			// Optional: Also update URL query param for immediate reflection
			const url = new URL(window.location);
			url.searchParams.set("locale", locale);
			window.history.replaceState({}, "", url.toString());
		} catch (error) {
			console.warn("Failed to save user locale preference:", error);
			// Strategy can still succeed even if save fails
		}
	},
});

// Server-side strategy - async database lookup
defineCustomServerStrategy("custom-userPreference", {
	getLocale: async (request) => {
		const userId = extractUserIdFromRequest(request);
		if (!userId) return undefined;

		try {
			// Async database call - this is now fully supported!
			return await getUserLocale(userId);
		} catch (error) {
			console.warn("Failed to fetch user locale from database:", error);
			return undefined; // Fallback to next strategy
		}
	},
});
```

--------------------------------

### Start a New Project with TanStack Router and Paraglide

Source: https://paraglidejs.com/tanstack-router

Use this command to scaffold a new project based on the official TanStack Router i18n example, which includes Paraglide JS.

```bash
npx gitpick TanStack/router/tree/main/examples/react/i18n-paraglide i18n-paraglide
```

--------------------------------

### Multi-tenancy Support Examples

Source: https://paraglidejs.com/changelog

Examples demonstrating multi-tenancy support in Paraglide JS 2.0, including domain-based and path-based routing strategies for sub-locales and root locales.

```shell
# Domain-based with sub-locale
customer1.fr/about         → French (default)
customer1.fr/en/about      → English version

# Domain-based with root locale
customer2.com/about        → English (default)
customer2.com/fr/about     → French version

# Path-based for any domain
example.com/en/about       → English
example.com/fr/about       → French
app.example.com/en/about   → English
app.example.com/fr/about   → French

```

--------------------------------

### Install Paraglide JS CLI

Source: https://paraglidejs.com/incremental-migration

Installs the latest version of Paraglide JS using npm.

```bash
npx @inlang/paraglide-js@latest init
Copy

```

--------------------------------

### i18next Format Example (en.json)

Source: https://paraglidejs.com/file-formats

Example of a translation file using the i18next format, suitable for migrating from i18next projects.

```json
{
	"greeting": "Hello {{name}}!",
	"items_count": "{{count}} item",
	"items_count_plural": "{{count}} items"
}
```

--------------------------------

### Inlang Message Format Example (de.json)

Source: https://paraglidejs.com/file-formats

German translation file example using the Inlang Message Format, demonstrating localized strings for placeholders and pluralization.

```json
{
	"greeting": "Hallo {name}!",
	"items_count": "{count, plural, one {# Artikel} other {# Artikel}}",
	"welcome_message": "Willkommen bei {appName}, {username}!"
}
```

--------------------------------

### Inlang Message Format Example (en.json)

Source: https://paraglidejs.com/file-formats

Example of a translation file using the Inlang Message Format, supporting placeholders and pluralization.

```json
{
	"greeting": "Hello {name}!",
	"items_count": "{count, plural, one {# item} other {# items}}",
	"welcome_message": "Welcome to {appName}, {username}!"
}
```

--------------------------------

### Using Multiple Plugins in project.inlang/settings.json

Source: https://paraglidejs.com/file-formats

Example of configuring multiple plugins in `project.inlang/settings.json` to support different translation file formats within the same project.

```json
{
	"baseLocale": "en",
	"locales": ["en", "de"],
	"modules": [
		"https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@4.4.0/dist/index.js",
		"https://cdn.jsdelivr.net/npm/@inlang/plugin-i18next@6.0.11/dist/index.js"
	]
}
```

--------------------------------

### TanStack Start Server Fetch Handler

Source: https://paraglidejs.com/middleware

Implement the fetch handler for TanStack Start, passing the original request object to paraglideMiddleware to avoid redirect loops. The handler's fetch method is called within the middleware callback.

```typescript
// server.ts
import { paraglideMiddleware } from "./paraglide/server.js";
import handler from "@tanstack/react-start/server-entry";

export default {
	fetch(req: Request): Promise<Response> {
		// Pass original `req` - NOT the modified `request` from callback
		return paraglideMiddleware(req, () => handler.fetch(req));
	},
};

```

--------------------------------

### Basic SSR Setup with paraglideMiddleware

Source: https://paraglidejs.com/server-side-rendering

Integrate `paraglideMiddleware` into your server to handle SSR requests. It automatically manages locale detection and isolation for each request.

```javascript
import { paraglideMiddleware } from './paraglide/server.js';

app.get("*", async (request) => {
  return paraglideMiddleware(request, async ({ request, locale }) => {
    return new Response(html(request));
  });
});
```

--------------------------------

### Get Help for Paraglide CLI

Source: https://paraglidejs.com/compiling-messages

Use the --help flag to view all available options for the Paraglide JS CLI compiler.

```bash
npx @inlang/paraglide-js compile --help
```

--------------------------------

### Pluralization Example

Source: https://paraglidejs.com/

Demonstrates how to use the `plural` formatter for singular and plural forms of a message. This works correctly for complex locales with different pluralization rules.

```javascript
// 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.)
```

--------------------------------

### Hono Framework Example

Source: https://paraglidejs.com/standalone-servers

Integrates Paraglide JS middleware with Hono for locale detection. The middleware processes the raw request and calls the next handler.

```javascript
import { Hono } from 'hono'
import { paraglideMiddleware } from './src/paraglide/server.js'
import { getLocale } from './src/paraglide/runtime.js'
import * as m from './src/paraglide/messages.js'

const app = new Hono()

app.use('*', (c, next) => {
  return paraglideMiddleware(c.req.raw, () => next())
})

app.get('/', (c) => {
  return c.json({
    locale: getLocale(),
    message: m.hello({ name: 'World' }),
  })
})

export default app
```

--------------------------------

### Astro Middleware Setup

Source: https://paraglidejs.com/middleware

Configure ParaglideJS middleware within an Astro project using defineMiddleware. The context request is passed to the paraglideMiddleware.

```typescript
// src/middleware.ts
import { paraglideMiddleware } from "./paraglide/server.js";
import { defineMiddleware } from "astro:middleware";

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

```

--------------------------------

### Express Framework Example

Source: https://paraglidejs.com/standalone-servers

Sets up Paraglide JS middleware for Express by converting Node.js request/response objects to Web API Request. The locale is attached to the request object.

```javascript
import express from 'express'
import { paraglideMiddleware } from './src/paraglide/server.js'
import { getLocale } from './src/paraglide/runtime.js'
import * as m from './src/paraglide/messages.js'

const app = express()

app.use(async (req, res, next) => {
  const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
  const webRequest = new Request(url, {
    method: req.method,
    headers: new Headers(req.headers as Record<string, string>),
  })

  await paraglideMiddleware(webRequest, async ({ locale }) => {
    req.locale = locale
    return new Response()
  })

  next()
})

app.get('/', (req, res) => {
  res.json({
    locale: getLocale(),
    message: m.hello({ name: 'World' }),
  })
})

app.listen(3000)
```

--------------------------------

### Example of valid JSON structure in translation

Source: https://paraglidejs.com/objects-and-arrays

A simple key-value pair example showing how translators typically see and edit string values in translation tools.

```text
┌─────────────────┬─────────────────────┐
│ Key             │ Value               │
├─────────────────┼─────────────────────┤
│ greeting        │ Hello world         │
│ farewell        │ Goodbye             │
└─────────────────┴─────────────────────┘
Copy

```

--------------------------------

### Define Custom Server-Side Strategy (Sync)

Source: https://paraglidejs.com/middleware

Define a synchronous custom server-side strategy using `defineCustomServerStrategy`. This example retrieves the locale from the `X-Locale` header.

```typescript
import { defineCustomServerStrategy } from "./paraglide/runtime.js";

// Sync example
defineCustomServerStrategy("custom-header", {
	getLocale: (request) => request?.headers.get("X-Locale") ?? undefined,
});
```

--------------------------------

### Configure Paraglide with Custom Strategies

Source: https://paraglidejs.com/strategy

Example of configuring Paraglide's build process to include custom locale strategies alongside built-in ones. Custom strategies must be prefixed with `custom-`.

```javascript
compile({
	project: "./project.inlang",
	outdir: "./src/paraglide",
+ 	strategy: ["custom-userPreferences", "cookie", "baseLocale"]
})
```

--------------------------------

### Detailed Middleware Lifecycle

Source: https://paraglidejs.com/middleware

Explains the step-by-step process within the Paraglide middleware, from locale detection and redirect checks to URL delocalization, async local storage setup, and finally, invoking your custom handler.

```text
  Incoming Request
        │
        ▼
┌───────────────────┐
│ 1. LOCALE         │  Evaluate strategies in order:
│    DETECTION      │  url → cookie → preferredLanguage → baseLocale
│                   │  First strategy that returns a locale wins.
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ 2. REDIRECT       │  If URL strategy is used AND URL doesn't match
│    CHECK          │  the detected locale → redirect (307) to correct URL.
│                   │  Only redirects "document" requests (not API/assets).
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ 3. URL            │  If URL strategy is used:
│    DELOCALIZATION │  /de/about → /about (strips locale prefix)
│                   │  Your app receives the "clean" URL.
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ 4. ASYNC LOCAL    │  Wraps request in AsyncLocalStorage context.
│    STORAGE        │  getLocale() returns correct locale for THIS request.
│                   │  Prevents locale bleeding between concurrent requests.
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ 5. YOUR HANDLER   │  Your resolve() callback runs here.
│    (resolve)      │  Call getLocale(), use messages, render your app.
└───────────────────┘
        │
        ▼
    Response
```

--------------------------------

### Web App Importing from Shared i18n Package

Source: https://paraglidejs.com/monorepo

Example of a web application importing messages and the runtime from a shared '@myorg/i18n' package.

```typescript
// packages/web/src/app.ts
import * as m from "@myorg/i18n/messages";
import { getLocale } from "@myorg/i18n/runtime";
```

--------------------------------

### TanStack Start SSR Integration

Source: https://paraglidejs.com/

Integrate Paraglide.js middleware with TanStack Start's server entry point to handle incoming requests with locale detection before passing them to the TanStack handler.

```typescript
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));
  },
};
```

--------------------------------

### Integrate with Framework SSG APIs (SvelteKit)

Source: https://paraglidejs.com/runtime

Example of using `generateStaticLocalizedUrls` within a SvelteKit `entries` function to define pages for pre-rendering. Requires `extractLocaleFromUrl`.

```javascript
// SvelteKit
export function entries() {
  const paths = ["/", "/about", "/contact"];
  return generateStaticLocalizedUrls(paths).map(url => ({
    locale: extractLocaleFromUrl(url)
  }));
}
```

--------------------------------

### URLPattern API Migration Guide

Source: https://paraglidejs.com/changelog

Migrate from `localizedNamedGroups` to the new tuple-based `localized` array in URL patterns for more intuitive and flexible translated pathnames.

```json
{
	"pattern": "https://:domain(.*)/:locale(de|fr)?/:path*",
	"deLocalizedNamedGroups": { "locale": null },
	"localizedNamedGroups": {
		"en": { "locale": null },
		"fr": { "locale": "fr" },
		"de": { "locale": "de" }
	}
}
```

```json
{
  "pattern": "https://:domain(.*)/:path*",
  "localized": [
    ["fr", "https://:domain(.*)/fr/:path*"],
    ["de", "https://:domain(.*)/de/:path*"]
    ["en", "https://:domain(.*)/:path*"]
  ]
}
```

--------------------------------

### Elysia Framework Example

Source: https://paraglidejs.com/standalone-servers

Implements Paraglide JS middleware in Elysia using the derive hook to set the locale. The middleware processes the request and extracts the locale.

```javascript
import { Elysia } from 'elysia'
import { paraglideMiddleware } from './src/paraglide/server.js'
import { getLocale } from './src/paraglide/runtime.js'
import * as m from './src/paraglide/messages.js'

const app = new Elysia()
  .derive(async ({ request }) => {
    let locale = 'en'
    await paraglideMiddleware(request, async ({ locale: l }) => {
      locale = l
      return new Response()
    })
    return { locale }
  })
  .get('/', () => ({
    locale: getLocale(),
    message: m.hello({ name: 'World' }),
  }))
  .listen(3000)
```

--------------------------------

### Define Message with Markup

Source: https://paraglidejs.com/markup

Example of a message definition in JSON format that includes basic markup tags like bold and icons.

```json
{
	"welcome": "{#b}Hi {name}{/b}{#icon/}"
}
```

--------------------------------

### Fastify Framework Example

Source: https://paraglidejs.com/standalone-servers

Integrates Paraglide JS middleware with Fastify using a preHandler hook. It converts the request to a Web API Request and attaches the detected locale to the request object.

```javascript
import Fastify from 'fastify'
import { paraglideMiddleware } from './src/paraglide/server.js'
import { getLocale } from './src/paraglide/runtime.js'
import * as m from './src/paraglide/messages.js'

const app = Fastify()

app.addHook('preHandler', async (req, reply) => {
  const url = `${req.protocol}://${req.hostname}${req.url}`
  const webRequest = new Request(url, {
    method: req.method,
    headers: new Headers(req.headers as Record<string, string>),
  })

  await paraglideMiddleware(webRequest, async ({ locale }) => {
    req.locale = locale
    return new Response()
  })
})

app.get('/', async (req, reply) => {
  return {
    locale: getLocale(),
    message: m.hello({ name: 'World' }),
  }
})

app.listen({ port: 3000 })
```

--------------------------------

### Web App Initializing Shared UI i18n

Source: https://paraglidejs.com/monorepo

Example of a web application initializing the shared UI internationalization functions with its own locale detection and setting logic.

```typescript
// packages/web/src/main.ts
import { getLocale, setLocale } from "./paraglide/runtime.js";
import { initUiI18n } from "@myorg/ui/i18n";

initUiI18n({ getLocale, setLocale });
```

--------------------------------

### Configure URL Patterns for Locale Prefixing

Source: https://paraglidejs.com/i18n-routing

Sets up URL patterns for locale prefixing, where each locale has its own path prefix. This example configures Paraglide to use '/de/:path(.*)?' for German and '/:path(.*)?' for English, with a wildcard for general path matching.

```javascript
compile({
	project: "./project.inlang",
	outdir: "./src/paraglide",
	strategy: ["url", "cookie"],
	urlPatterns: [
		{
			pattern: "/:path(.*)?",
			localized: [
				["de", "/de/:path(.*)?"],
				// make sure to match the least specific path last
				["en", "/:path(.*)?"],
			],
		},
	]});

```

--------------------------------

### Define Custom Client-Side Strategy

Source: https://paraglidejs.com/middleware

Use `defineCustomClientStrategy` to create a custom strategy for client-side locale detection. This example uses `sessionStorage` to store and retrieve the locale.

```typescript
import { defineCustomClientStrategy } from "./paraglide/runtime.js";

defineCustomClientStrategy("custom-sessionStorage", {
	getLocale: () => sessionStorage.getItem("locale") ?? undefined,
	setLocale: (locale) => sessionStorage.setItem("locale", locale),
});
```

--------------------------------

### Server-Side Locale Resolution with AsyncLocalStorage

Source: https://paraglidejs.com/strategy

On the server, use `AsyncLocalStorage` to manage locale resolution and avoid race conditions when multiple requests arrive with different locales. This example demonstrates setting up `AsyncLocalStorage` for locale management.

```javascript
import { m } from "./paraglide/messages.js";
import { overwriteGetLocale, baseLocale } from "./paraglide/runtime.js";
import { AsyncLocalStorage } from "node:async_hooks";
const localeStorage = new AsyncLocalStorage();


```

--------------------------------

### Define Custom Server-Side Strategy (Async)

Source: https://paraglidejs.com/middleware

Define an asynchronous custom server-side strategy for operations like database lookups. This example fetches the user's locale from a database based on their ID.

```typescript
import { defineCustomServerStrategy } from "./paraglide/runtime.js";

// Async example (database lookup)
defineCustomServerStrategy("custom-database", {
	getLocale: async (request) => {
		const userId = extractUserId(request);
		if (!userId) return undefined;
		return await getUserLocaleFromDB(userId);
	},
});
```

--------------------------------

### Configure Locale Detection Strategy (CLI)

Source: https://paraglidejs.com/standalone-servers

Configures the locale detection strategy via the CLI using comma-separated values for the --strategy flag. This allows for flexible locale detection setup.

```bash
npx @inlang/paraglide-js compile \
  --project ./project.inlang \
  --outdir ./src/paraglide \
  --strategy url,cookie,preferredLanguage,baseLocale
```

--------------------------------

### Next.js App Router Middleware Integration

Source: https://paraglidejs.com/middleware

Set up the paraglideMiddleware for Next.js applications using the App Router. This example shows how to use NextResponse.next() to continue the request processing.

```typescript
// middleware.ts
import { paraglideMiddleware } from "./paraglide/server.js";
import { NextResponse } from "next/server";

export async function middleware(request: Request) {
	return paraglideMiddleware(request, async ({ request, locale }) => {
		return NextResponse.next();
	});
}

```

--------------------------------

### Configure Strategy with Global Variable

Source: https://paraglidejs.com/strategy

Use this configuration to determine the locale from a global variable. This strategy is primarily for testing or quick setups and is not recommended for production server-side or client-side environments due to potential cross-request issues and lack of persistence.

```javascript
compile({
	project: "./project.inlang",
	outdir: "./src/paraglide",
	strategy: ["globalVariable"]
})
```

--------------------------------

### Initialize Paraglide JS

Source: https://paraglidejs.com/react-i18next-alternatives

Use this command to initialize Paraglide JS in your project. This sets up the necessary configuration and files for the library.

```bash
npx @inlang/paraglide-js init
```

--------------------------------

### Monorepo Directory Structure (Pattern 1)

Source: https://paraglidejs.com/monorepo

Illustrates the recommended directory structure for Pattern 1, where each consuming package has its own Paraglide generation directory.

```bash
monorepo/
+ project.inlang/           # Shared inlang project
+ messages/
+   en.json
+   de.json
  packages/
    web/
      src/paraglide/        # Generated here
      vite.config.ts
    mobile/
      src/paraglide/        # Generated here
      vite.config.ts
```

--------------------------------

### Get message parts with dynamic data

Source: https://paraglidejs.com/markup

Call `m.welcome.parts({ name: "Ada" })` to get message parts that include dynamic data. The parts array will contain text and markup elements, reflecting the structure defined in the message, such as bold tags and standalone icons.

```javascript
const parts = m.welcome.parts({ name: "Ada" });
/*
[
  { type: "markup-start", name: "b", options: {}, attributes: {} },
  { type: "text", value: "Hi " },
  { type: "text", value: "Ada" },
  { type: "markup-end", name: "b", options: {}, attributes: {} },
  { type: "markup-standalone", name: "icon", options: {}, attributes: {} }
]
*/
```

--------------------------------

### CustomServerStrategyHandler

Source: https://paraglidejs.com/runtime

Handles custom server-side locale strategies. Allows getting the locale from a request.

```APIDOC
## CustomServerStrategyHandler

### Description
Handles custom server-side locale strategies. Allows getting the locale from a request.

### Methods
#### getLocale(request?)
Gets the locale from the incoming request.

- **Parameters**:
  - **request?** (`Request`) - The incoming request object.
- **Returns**: `Promise<string | undefined> | string | undefined`
```

--------------------------------

### CustomClientStrategyHandler

Source: https://paraglidejs.com/runtime

Handles custom client-side locale strategies. Allows getting and setting the current locale.

```APIDOC
## CustomClientStrategyHandler

### Description
Handles custom client-side locale strategies. Allows getting and setting the current locale.

### Methods
#### getLocale()
Gets the current locale.

- **Returns**: `Promise<string | undefined> | string | undefined`

#### setLocale(locale)
Sets the current locale.

- **Parameters**:
  - **locale** (`string`) - The locale to set.
- **Returns**: `Promise<void> | void`
```

--------------------------------

### Define Messages in JSON

Source: https://paraglidejs.com/vite

Example of a messages file in JSON format. Unused messages are automatically removed from the bundle.

```json
{ "greeting": "Hello {name}!", "unused": "I'm never used" }
```

--------------------------------

### New .meta.json file in inlang projects

Source: https://paraglidejs.com/changelog

The SDK now writes a .meta.json file to track which SDK version last modified the project. This enables safe forward migrations and prevents accidental downgrades when switching between SDK versions.

```bash
project.inlang/
  settings.json
  README.md
  .gitignore
  .meta.json   <-- new
```

--------------------------------

### Ordinal Pluralization

Source: https://paraglidejs.com/variants

Request ordinal categories from `Intl.PluralRules` by passing `type=ordinal`. This example handles 1st, 2nd, 3rd, and other places.

```json
{
  "finished_readout": [{
    "declarations": [
      "input placeNumber",
      "local ordinalCategory = placeNumber: plural type=ordinal"
    ],
    "selectors": ["ordinalCategory"],
    "match": {
      "ordinalCategory=one": "You finished in {placeNumber}st place",
      "ordinalCategory=two": "You finished in {placeNumber}nd place",
      "ordinalCategory=few": "You finished in {placeNumber}rd place",
      "ordinalCategory=*": "You finished in {placeNumber}th place"
    }
  }]
}
```

--------------------------------

### Hono Application Middleware

Source: https://paraglidejs.com/middleware

Integrate ParaglideJS middleware into a Hono application. This example uses a wildcard route and returns the locale in the response.

```typescript
import { Hono } from "hono";
import { paraglideMiddleware } from "./paraglide/server.js";

const app = new Hono();

app.use("*", async (c) => {
	return paraglideMiddleware(c.req.raw, async ({ request, locale }) => {
		// Your route handling here
		return c.text(`Locale: ${locale}`);
	});
});

export default app;

```

--------------------------------

### Configure Tenant-Specific Locales with compile

Source: https://paraglidejs.com/multi-tenancy

Use the `compile` function to define tenant-specific URL patterns and locale mappings. Unsupported locales are mapped to a 404 page.

```javascript
compile({
	project: "./project.inlang",
	outdir: "./src/paraglide",
	strategy: ["url", "baseLocale"],
	urlPatterns: [
		// Customer1 - only supports en and de
		{
			pattern: "https://customer1.com/:path(.*)?",
			localized: [
				["en", "https://customer1.com/:path(.*)?"],
				["de", "https://customer1.com/de/:path(.*)?"],
				["fr", "https://customer1.com/404"],  // Unsupported → 404
				["es", "https://customer1.com/404"],
			],
		},
		// Customer2 - only supports fr and es
		{
			pattern: "https://customer2.com/:path(.*)?",
			localized: [
				["fr", "https://customer2.com/:path(.*)?"],
				["es", "https://customer2.com/es/:path(.*)?"],
				["en", "https://customer2.com/404"],  // Unsupported → 404
				["de", "https://customer2.com/404"],
			],
		},
		// Customer3 - supports all locales
		{
			pattern: "https://customer3.com/:path(.*)?",
			localized: [
				["en", "https://customer3.com/:path(.*)?"],
				["de", "https://customer3.com/de/:path(.*)?"],
				["fr", "https://customer3.com/fr/:path(.*)?"],
				["es", "https://customer3.com/es/:path(.*)?"],
			],
		},
	],
});

```

--------------------------------

### Dynamic Messages for Tree-Shaking

Source: https://paraglidejs.com/basics

Specify messages beforehand in an object to ensure they are preserved during tree-shaking. This example shows how to dynamically access messages.

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

messages["greeting"](); // "Hello World!"
```

--------------------------------

### Enable Pre-rendering in SvelteKit

Source: https://paraglidejs.com/sveltekit

Configure your SvelteKit layout to enable pre-rendering for static site generation. This is a key step for generating all pages at build time.

```javascript
// routes/+layout.ts
+export const prerender = true;
```

--------------------------------

### Message File Structure

Source: https://paraglidejs.com/basics

Messages are stored in `messages/{locale}.json` files. The examples show the structure for English and German messages.

```json
{
  "greeting": "Hello {name}!"
}
```

```json
{
  "greeting": "Hallo {name}!"
}
```

--------------------------------

### Generate Localized URLs for SSG

Source: https://paraglidejs.com/static-site-generation

Use `generateStaticLocalizedUrls` to get all localized URLs from your patterns. This is useful for sitemap generation and hreflang tags.

```javascript
import { generateStaticLocalizedUrls } from "./paraglide/runtime.js";

const localizedUrls = generateStaticLocalizedUrls([
  "/",
  "/about",
  "/blog",
  "/blog/post-1",
  "/blog/post-2",
]);

console.log(localizedUrls);
// [
//   "/en/", "/de/",
//   "/en/about", "/de/about",
//   "/en/blog", "/de/blog",
//   "/en/blog/post-1", "/de/blog/post-1",
//   "/en/blog/post-2", "/de/blog/post-2"
// ]
```

--------------------------------

### Configure Multi-Tenancy URL Patterns

Source: https://paraglidejs.com/multi-tenancy

Define custom routing rules for different tenant domains using `urlPatterns`. This configuration supports development with localhost and specific patterns for various customer domains, including default locales and path-based localization.

```javascript
compile({
	project: "./project.inlang",
	outdir: "./src/paraglide",
	strategy: ["url", "baseLocale"],
	urlPatterns: [
		// Localhost for development (use path prefixes)
		{
			pattern: "http://localhost::port?/:path(.*)?",
			localized: [
				["fr", "http://localhost::port?/fr/:path(.*)?"],
				["en", "http://localhost::port?/:path(.*)?"],
			],
		},
		// customer1.fr => French default, English via /en/
		{
			pattern: "https://customer1.fr/:path(.*)?",
			localized: [
				["fr", "https://customer1.fr/:path(.*)?"],
				["en", "https://customer1.fr/en/:path(.*)?"],
			],
		},
		// customer2.com => English default, French via /fr/
		{
			pattern: "https://customer2.com/:path(.*)?",
			localized: [
				["en", "https://customer2.com/:path(.*)?"],
				["fr", "https://customer2.com/fr/:path(.*)?"],
			],
		},
	],
});

```

--------------------------------

### Getting and Setting Locale

Source: https://paraglidejs.com/basics

Use `getLocale`, `getTextDirection`, and `setLocale` from `./paraglide/runtime.js` to manage the current locale. `setLocale` reloads the page by default.

```javascript
import { getLocale, getTextDirection, setLocale } from "./paraglide/runtime.js";

getLocale(); // "en"
getTextDirection(); // "ltr" or "rtl" for current locale
setLocale("de"); // Changes locale and reloads page
```

--------------------------------

### Solid: Render Message with Link Markup

Source: https://paraglidejs.com/markup

Example of using ParaglideMessage in a SolidJS component to render a message with a custom 'link' markup renderer.

```jsx
import { ParaglideMessage } from "@inlang/paraglide-js-solid";
import { m } from "./paraglide/messages.js";

const view = (
	<ParaglideMessage
		message={m.cta}
		inputs={{}}
		markup={{
			link: ({ children, options }) => <a href={options.to}>{children}</a>,
		}}
	/>
);

```

--------------------------------

### Correct Message Usage with URL Strategy

Source: https://paraglidejs.com/errors

Demonstrates the correct way to use messages with the 'url' strategy by ensuring they are called within a request context, typically set by `paraglideMiddleware`.

```javascript
// hello.ts
import { m } from "./paraglide/messages.js";

app.use(paraglideMiddleware);

// ✅ this will work
app.get("/", (req, res) => {
	console.log(m.hello());
});
```

--------------------------------

### React: Render Message with Link Markup

Source: https://paraglidejs.com/markup

Example of using ParaglideMessage in a React component to render a message with a custom 'link' markup renderer.

```jsx
import { ParaglideMessage } from "@inlang/paraglide-js-react";
import { m } from "./paraglide/messages.js";

export function ContactCta() {
	return (
		<ParaglideMessage
			message={m.cta}
			inputs={{}}
			markup={{
				link: ({ children, options, attributes }) => (
					<a
						href={options.to}
						data-track={attributes.track === true ? "true" : "false"}
					>
						{children}
					</a>
				),
			}}
		/>
	);
}
```

--------------------------------

### Update app.html with %lang% and %dir%

Source: https://paraglidejs.com/sveltekit

Modify your src/app.html file to include the %lang% and %dir% placeholders in the html tag.

```html
<!doctype html>
<html lang="%lang%" dir="%dir%">
	...
</html>

```

--------------------------------

### Number Formatting with Options

Source: https://paraglidejs.com/formatting

Configure number formatting by passing options like minimumFractionDigits, maximumFractionDigits, style, and currency. These options are forwarded to Intl.NumberFormat.

```json
{
  "balance_fixed_decimals": [{
    "declarations": [
      "input amount",
      "local formattedAmount = amount: number minimumFractionDigits=2 maximumFractionDigits=2"
    ],
    "match": {
      "amount=*": "Balance: {formattedAmount}."
    }
  }],
  "price_in_usd": [{
    "declarations": [
      "input amount",
      "local formattedAmount = amount: number style=currency currency=USD"
    ],
    "match": {
      "amount=*": "Price: {formattedAmount}"
    }
  }]
}
```

--------------------------------

### Calculating Relative Duration Before Formatting

Source: https://paraglidejs.com/formatting

Compute the duration and unit before calling the message function. This example converts minutes into days, hours, or minutes.

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

function toRelativeDuration(minutes: number) {
  const absoluteMinutes = Math.abs(minutes);

  if (absoluteMinutes >= 60 * 24) {
    return {
      duration: Math.round(minutes / (60 * 24)),
      unit: "day",
    };
  }

  if (absoluteMinutes >= 60) {
    return {
      duration: Math.round(minutes / 60),
      unit: "hour",
    };
  }

  return {
    duration: minutes,
    unit: "minute",
  };
}

const relative = toRelativeDuration(-125);
m.relative_update(relative);
```

--------------------------------

### Enable URL-based Locale Detection

Source: https://paraglidejs.com/i18n-routing

Add 'url' to your strategy array to enable URL-based locale detection. This is the default setup for locale prefixes.

```javascript
compile({
	project: "./project.inlang",
	outdir: "./src/paraglide",
	strategy: ["url", "baseLocale"],
});
```

--------------------------------

### Correct URL Pattern Order

Source: https://paraglidejs.com/i18n-routing

Demonstrates the correct order of URL patterns, placing more specific patterns before general wildcard patterns to ensure correct matching.

```javascript
urlPatterns: [
	{
		pattern: "https://example.com/blog/:id", // Specific pattern first
		localized: [
			["en", "https://example.com/blog/:id"],
			["de", "https://example.com/de/blog/:id"],
		],
	},
	{
		pattern: "https://example.com/:path(.*)?", // General pattern last
		localized: [
			["en", "https://example.com/:path(.*)?"],
			["de", "https://example.com/de/:path(.*)?"],
		],
	},
];
```

--------------------------------

### Compile Messages Programmatically

Source: https://paraglidejs.com/standalone-servers

Compiles messages programmatically at application startup. Ensure the project and outdir paths are correctly configured.

```javascript
import { compile } from '@inlang/paraglide-js'

await compile({
  project: './project.inlang',
  outdir: './src/paraglide',
})
```

--------------------------------

### Bundle Output with Tree-Shaking

Source: https://paraglidejs.com/vite

Illustrates the bundle output after Vite's tree-shaking has removed unused messages. Only the 'greeting' function is included.

```javascript
function greeting(params) { return `Hello ${params.name}!`; }
- function unused() { return "I'm never used"; }
```

--------------------------------

### overwriteSetLocale()

Source: https://paraglidejs.com/runtime

Overwrite the `setLocale()` function. Use this function to overwrite how the locale is set. For example, modify a cookie, env variable, or a user's preference.

```APIDOC
## overwriteSetLocale()

### Description
Overwrite the `setLocale()` function. Use this function to overwrite how the locale is set. For example, modify a cookie, env variable, or a user's preference.

### Parameters
#### fn
- `fn` (`SetLocaleFn`) - The new implementation for `setLocale()`.

### Returns
`void`

### Example
```javascript
overwriteSetLocale((newLocale) => {
    // set the locale in a cookie
    return Cookies.set('locale', newLocale)
  });
```
```

--------------------------------

### SvelteKit: Prerender Dynamic Routes with Locale and Slug

Source: https://paraglidejs.com/static-site-generation

For dynamic routes in SvelteKit, enumerate all locale and slug combinations using the `entries` export. Requires data fetching for slugs.

```typescript
// src/routes/[locale]/blog/[slug]/+page.ts
import { locales } from "$paraglide/runtime.js";

export const prerender = true;

export async function entries() {
  const posts = await getPosts(); // Your data fetching

  // Generate all locale + slug combinations
  return locales.flatMap((locale) =>
    posts.map((post) => ({ locale, slug: post.slug }))
  );
}
```

--------------------------------

### Adding Locales Configuration

Source: https://paraglidejs.com/basics

Define the base locale and available locales in `project.inlang/settings.json`.

```json
{
  "baseLocale": "en",
  "locales": ["en", "de", "fr"]
}
```

--------------------------------

### Emit .gitignore File

Source: https://paraglidejs.com/compiler-options

Set `emitGitIgnore` to `true` to automatically generate a `.gitignore` file in the output directory. This prevents accidentally committing generated files.

```plaintext
  - outdir/
    - messages/
+   - .gitignore
    - messages.js
    - runtime.js
```

--------------------------------

### URL Strategy and Message Context

Source: https://paraglidejs.com/errors

When using the 'url' strategy, ensure messages are called within a request context. This example shows an incorrect usage.

```javascript
strategy: ["url"]
```

```javascript
// hello.ts
import { m } from "./paraglide/messages.js";

// 💥 there is no url in this context to retrieve
//    the locale from.
console.log(m.hello());
```

--------------------------------

### Date and Time Formatting with Options

Source: https://paraglidejs.com/formatting

Customize date and time formatting by passing options such as dateStyle, timeStyle, and timeZone. These options are forwarded to Intl.DateTimeFormat. Use an explicit timeZone for stable output.

```json
{
  "event_start": [{
    "declarations": [
      "input date",
      "local formattedDate = date: datetime dateStyle=long timeStyle=short timeZone=UTC"
    ],
    "match": {
      "date=*": "Starts: {formattedDate}"
    }
  }]
}
```

--------------------------------

### Configuring Fallback Locale Strategy

Source: https://paraglidejs.com/server-side-rendering

Illustrates how to configure locale detection strategies, ensuring a fallback to `baseLocale` if no other strategy resolves the locale.

```javascript
strategy: ["url", "cookie", "baseLocale"]
```

--------------------------------

### Set Output Directory for Paraglide Compilation

Source: https://paraglidejs.com/compiler-options

Specify the output directory for the compiled Paraglide JS files. This example shows how to set it within the `compile` function.

```javascript
await compile({
  project: "./project.inlang",
+ outdir: "./src/paraglide"
})
```

--------------------------------

### Translator accidentally breaks JSON syntax

Source: https://paraglidejs.com/objects-and-arrays

Example of a translator making a mistake by removing quotes, which can lead to runtime errors due to invalid JSON syntax.

```text
// Translator accidentally removes a quote
- ["Fast", "Secure", "Easy to use"]
+ ["Schnell", "Sicher, "Einfach"]
Copy

```

--------------------------------

### Remove Adapter Packages

Source: https://paraglidejs.com/changelog

As of v2.0.0-beta.19, adapter packages are no longer needed. Remove them from your project and follow the documentation for SvelteKit.

```bash
-@inlang/paraglide-sveltekit
-@inlang/paraglide-next
-@inlang/paraglide-astro
```

--------------------------------

### Correct Localized Pattern Order

Source: https://paraglidejs.com/i18n-routing

Illustrates the correct order for localized URL patterns, placing specific patterns before general ones to ensure correct matching.

```javascript
// CORRECT ORDER: Specific patterns first, then more general patterns
{
  pattern: "https://example.com/:path(.*)?",
  localized:
    [
      ["en", "https://example.com/en/blog/:id"], // Specific pattern first
      ["en", "https://example.com/:path(.*)?"], // General pattern last
    ],
}
```

--------------------------------

### getTextDirection()

Source: https://paraglidejs.com/runtime

Gets the writing direction (LTR or RTL) for a specified locale. It leverages `Intl.Locale` for text information and falls back to a language-based check if `getTextInfo()` is unavailable.

```APIDOC
## getTextDirection(locale?)

### Description
Get writing direction for a locale. Uses `Intl.Locale` text info when available and falls back to a language-based RTL check for runtimes without `getTextInfo()`.

### Parameters
#### locale?
`string` = `...` - Target locale. If not provided, uses `getLocale()`.

### Returns
`"ltr"` | `"rtl"` - The writing direction of the locale.

### Example
```javascript
getTextDirection(); // "ltr" or "rtl" for current locale
getTextDirection("ar"); // "rtl"
getTextDirection("en"); // "ltr"
```
```

--------------------------------

### Emit README.md File

Source: https://paraglidejs.com/compiler-options

Set `emitReadme` to `true` to automatically generate a `README.md` file in the output directory. This file can help LLMs understand the compiled output.

```plaintext
  - outdir/
    - messages/
+   - README.md
    - messages.js
    - runtime.js
```

--------------------------------

### Usage of Paraglide JS Messages and Locale Functions

Source: https://paraglidejs.com/react-router

Import and use messages for translations, and functions to get and set the current locale within your React application.

```typescript
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
Copy

```

--------------------------------

### Working with Dynamic Keys

Source: https://paraglidejs.com/message-keys

Handle dynamic menu systems by creating explicit mappings for flat keys or using an array of objects for nested keys.

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

// With flat keys (recommended)
const navMessages = {
  home: m.nav_home,
  about: m.nav_about,
  contact: m.nav_contact,
} as const;

// With nested keys (if needed)
const menuItems = [
  { key: "nav.home", href: "/" },
  { key: "nav.about", href: "/about" },
] as const;

menuItems.forEach(item => {
  const label = m[item.key]();
  console.log(`<a href="https://raw.githubusercontent.com/opral/paraglide-js/refs/heads/main/docs/%3Cspan%20class=.md"hljs-subst">${item.href}">${label}</a>`);
});

```

--------------------------------

### Configure Strategy with Cookie Only

Source: https://paraglidejs.com/strategy

Configure Paraglide JS to only use the `cookie` strategy for determining the locale. This is a minimal setup focusing solely on cookie-based locale detection.

```javascript
compile({
	project: "./project.inlang",
	outdir: "./src/paraglide",
	strategy: ["cookie"]
})
```

--------------------------------

### Message Function Type Error Example

Source: https://paraglidejs.com/changelog

Illustrates a type error scenario after the introduction of type-safe literal unions for match variants. Previously, incorrect types were accepted.

```javascript
m.auth_password_error({ type: "typo" }); // ✅ OK (typed as NonNullable<unknown>)
```

```javascript
m.auth_password_error({ type: "typo" }); // 💥 Type error
```

--------------------------------

### ParaglideJS Compile CLI Flags

Source: https://paraglidejs.com/changelog

Use `--output-structure` to specify the output structure for the compile command.

```bash
paraglide-js compile --output-structure "./dist"
```

--------------------------------

### Recommended Flat Keys with Prefixes

Source: https://paraglidejs.com/message-keys

Organize related messages using prefixes with flat keys. This approach allows for direct function calls, perfect tree-shaking, and better IDE support.

```json
// messages/en.json
{
  "nav_home": "Home",
  "nav_about": "About", 
  "nav_contact": "Contact",
  "footer_privacy": "Privacy Policy",
  "footer_terms": "Terms of Service"
}
```

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

// ✅ Direct function calls with perfect tree-shaking
console.log(m.nav_home()); // "Home"

// ✅ Better IDE support with go-to-definition
// ✅ Cleaner imports with auto-import
// ✅ No runtime overhead
```

--------------------------------

### Lazy-load translations with init function

Source: https://paraglidejs.com/blog/dont-lazy-load

This configuration demonstrates how to lazy-load translations using an async import within the init function. This approach is discouraged due to potential performance impacts.

```javascript
init({
    translations: {
        en: async () => await import("./en.json"),
        de: async () => await import("./de.json"),
    }
})
```

--------------------------------

### Shared UI Component Accepting Translated String

Source: https://paraglidejs.com/monorepo

Example of a reusable UI component that accepts a translated string as a prop, keeping the UI package independent of Paraglide.

```typescript
// packages/ui/src/save-button.tsx
export function SaveButton(props: { label: string }) {
	return <button>{props.label}</button>;
}
```
Tokens:
Raw