Files
shumai/packages/webui/paraglide/README.md
T

5.4 KiB
Generated

Paraglide JS Compiled Output

Auto-generated i18n message functions. Import messages.js to use translated strings.

Compiled from: /Users/yiling/Projects/shumai/packages/webui/project.inlang

What is this folder?

This folder contains compiled Paraglide JS output. Paraglide JS compiles your translation messages into tree-shakeable JavaScript functions.

At a glance

Purpose:

  • This folder stores compiled i18n message functions.
  • Source translations live outside this folder in your inlang project.

Safe to import:

  • messages.js — all message functions
  • runtime.js — locale utilities
  • server.js — server-side middleware

Do not edit:

  • All files in this folder are auto-generated.
  • Changes will be overwritten on next compilation.
paraglide/
├── messages.js      # Message exports (import this)
├── messages/        # Individual message functions
├── runtime.js       # Locale detection & configuration
├── registry.js      # Formatting utilities (plural, number, datetime, relativetime)
├── server.js        # Server-side middleware
└── .gitignore       # Marks folder as generated

Usage

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

// Messages are functions that return localized strings
m.hello_world();             // "Hello, World!" (in current locale)
m.greeting({ name: "Sam" }); // "Hello, Sam!"

// Override locale per-call
m.hello_world({}, { locale: "de" });           // "Hallo, Welt!"
m.greeting({ name: "Sam" }, { locale: "de" }); // "Hallo, Sam!"

Runtime API

import { getLocale, getTextDirection, setLocale, locales, baseLocale } from "./paraglide/runtime.js";

getLocale();    // Current locale, e.g., "en"
getTextDirection(); // "ltr" | "rtl" for current locale
setLocale("de"); // Set locale
locales;        // Available locales, e.g., ["en", "de", "fr"]
baseLocale;     // Default locale, e.g., "en"

Strategy

The strategy determines how the current locale is detected and persisted:

  • Cookie: Stores locale preference in a cookie.
  • URL: Derives locale from URL patterns (e.g., /en/about, en.example.com).
  • GlobalVariable: Uses a global variable (client-side only).
  • BaseLocale: Always returns the base locale.

Strategies can be combined. The order defines precedence:

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

See the strategy documentation for details.

Markup (Rich Text)

Messages can contain markup tags for bold, links, and other inline elements. Translators control where tags appear; developers control how they render.

Important:

  • Tag names are app-defined. There is no built-in list of HTML tags.
  • {#b}...{/b} does not automatically render as <b>...</b>.
  • Renderers/snippets are looked up by the same tag name used in the message.

Message syntax

{
  "cta": "{#link to=|/docs| rel=$relationship @track}Read the docs{/link}",
  "welcome": "{#b}Hi {name}{/b}{#icon/}"
}
  • {#tagName} opens a tag, {/tagName} closes it.
  • {#tagName/} creates a standalone tag.
  • Options: to=|/docs| or rel=$relationship (accessed via options.*).
  • Attributes: @track or @variant=|hero| (accessed via attributes.*).

This is the default inlang message syntax. Paraglide's message format is plugin-based — you can use ICU MessageFormat 1, i18next, or other plugins instead.

Rendering markup

Calling the message function still returns plain text (markup stripped):

m.cta({ relationship: "noopener" }); // "Read the docs"

To render markup, use the framework adapter or the low-level parts() API:

const parts = m.cta.parts({ relationship: "noopener" });
// [
//   { type: "markup-start", name: "link", options: { to: "/docs", rel: "noopener" }, attributes: { track: true } },
//   { type: "text", value: "Read the docs" },
//   { type: "markup-end", name: "link" }
// ]

Framework adapters provide a <ParaglideMessage> component that accepts markup renderers:

  • @inlang/paraglide-js-react
  • @inlang/paraglide-js-vue
  • @inlang/paraglide-js-svelte
  • @inlang/paraglide-js-solid
import { ParaglideMessage } from "@inlang/paraglide-js-react"; // or -vue, -svelte, -solid

<ParaglideMessage
  message={m.welcome}
  inputs={{ name: "Ada" }}
  markup={{
    b: ({ children }) => <b>{children}</b>,
    icon: () => <span aria-hidden="true" className="icon-wave" />,
  }}
/>

The available renderer/snippet names come from the message itself. You can inspect them through message.parts(), and TypeScript uses the same names to type-check your markup renderers.

See the markup documentation for details.

Key concepts

  • Tree-shakeable: Each message is a function, enabling up to 70% smaller i18n bundle sizes than traditional i18n libraries.
  • Typesafe: Full TypeScript/JSDoc support with autocomplete.
  • Variants: Messages can have variants for pluralization, gender, etc.
  • Fallbacks: Missing translations fall back to the base locale.