Quickstart

The guided 5-minute path.

One translated component, one extraction run, one .po file, one runtime instance. “5-minute path” names this compact route through the real moving parts; it is not a completion-time guarantee.

See the local loop Full written guide

01 — The loop

Know the path before touching configuration.

The guided route follows the same cycle you will keep using after the first translation.

writeextracttranslaterenderrepeat

02 — Choose a host

Run the complete local loop in your stack.

Choose the nearest host, then work through install, configuration, authoring, extraction, translation, and rendering. The package caveat appears directly after the command it qualifies.

Install

Core, runtime, host adapter, and the build plugin — plus the CLI as a dev dependency.

pnpm add @palamedes/core @palamedes/react @palamedes/runtime @palamedes/vite-plugin
pnpm add -D @palamedes/cli @vitejs/plugin-react

02
Package boundary
Use the scoped packages
Install the scoped @palamedes/* packages shown above. The top-level palamedes and create-palamedes names are reserved for a future one-command setup and are not the entry point today.

Configure

One YAML file declares your locales and where catalogs live.

# palamedes.yaml
locales: [en, de]
source-locale: en
catalogs:
  - path: src/locales/{locale}
    include: [src]

Wire the plugin & runtime

The Vite plugin handles the macro transform and compiles .po catalogs; the runtime holds the active i18n instance.

// vite.config.ts
import { palamedes } from "@palamedes/vite-plugin"
export default defineConfig({ plugins: [palamedes(), react()] })

// src/i18n.ts
import { createI18n } from "@palamedes/core/compiled"
import { setClientI18n } from "@palamedes/runtime"

export const i18n = createI18n()
setClientI18n(i18n)

Write & extract

Author the message in your component, then run one command — it creates src/locales/en.po and de.po.

// src/App.tsx
import { t } from "@palamedes/core/macro"
export const App = () => <h1>{t`Welcome to Palamedes`}</h1>

$ pmds extract

Translate

Open the German catalog and fill in the translated string.

# src/locales/de.po
msgid "Welcome to Palamedes"
msgstr "Willkommen bei Palamedes"

07
Load & see it render
Load the catalogs, activate a locale, and run the dev server — the page now renders “Willkommen bei Palamedes”. That is the full local loop: transform, extraction, catalog, runtime.
```
// src/main.tsx
import { i18n } from "./i18n"
import { messages as enMessages } from "./locales/en.po"
import { messages as deMessages } from "./locales/de.po"

i18n.load("en", enMessages)
i18n.load("de", deMessages)
i18n.activate("de")

$ pnpm dev
```
Aside
TypeScript needs an ambient declaration for .po imports — add a src/po.d.ts with `declare module "*.po"` (see the troubleshooting guide).

03 — Next

Carry the model into the application.

Plurals, dates & currency

ICU MessageFormat with authoring diagnostics that catch mistakes at extract time.

Pick a locale strategy

Cookie, route, subdomain, or TLD — with a live demo for each, in your framework.

Localize your backend

Request-local i18n for Hono and Express from the same catalogs.

Migrating from Lingui?

A step-by-step playbook. Source-string-first .po catalogs are often reusable after an extraction pass; explicit-ID setups need cleanup.

Something broke?

The troubleshooting guide covers the common setup failures with exact error messages.

Using an AI assistant?

Point it at llms.txt — the whole API surface in one machine-readable file.

Choose the production shape that comes next.

Choose your framework Explore locale architecture