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 adapter owns the parser-free runtime and derives the active locale's compiled catalog dependency before translated code runs.

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

// index.html
<html lang="de"></html>

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
See it render
The adapter derives and loads the active locale's compiled fragment before translated code runs — the page now renders “Willkommen bei Palamedes”.
```
$ pnpm dev
```
Aside
No app-owned catalog map, locale import, or runtime loader is required in the standard flow.

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