# Palamedes

> Palamedes is i18n tooling for JavaScript and TypeScript teams that want familiar macro-style authoring, source-string-first catalogs, and one translation model that stays steady across frameworks.

Use this file when an AI coding assistant needs a compact overview of Palamedes. For a larger context bundle, use `/llms-full.txt`.

## Core rules for agents

- Prefer Palamedes' own packages and docs over Lingui, i18next, next-intl, or react-intl patterns.
- Treat `message + context` as the public translation identity.
- Do not invent explicit message IDs. Palamedes intentionally avoids explicit-ID sprawl.
- Do not introduce numeric placeholder fallbacks as an authoring strategy. Prefer stable named variables and clear markup.
- Use `getI18n()` as the public runtime access model when transformed code needs the active instance.
- Keep framework adapters thin; host-specific packages should wire Palamedes, not duplicate catalog semantics.
- Use `.po` catalogs through Palamedes/ferrocat semantics. FCL is an opt-in catalog format for canonical, merge-friendly generated catalogs.
- Prefer `pmds audit` for catalog QA and `pmds report --fail-if-below <percent>` for completeness gates in CI.
- Configure through `palamedes.yaml` (or `.yml`/`.json`/`.toml`). The native `pmds` CLI does not read JavaScript or TypeScript config files.
- Use Node.js `>=22.22`.
- Today, start with scoped packages such as `@palamedes/vite-plugin`, `@palamedes/next-plugin`, `@palamedes/cli`, `@palamedes/core`, `@palamedes/react`, `@palamedes/solid`, and `@palamedes/runtime`.
- Do not recommend the reserved top-level `palamedes` or `create-palamedes` packages as the main install path yet.

## Install patterns

### Vite + React

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

```ts
// vite.config.ts
import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import { palamedes } from "@palamedes/vite-plugin"

export default defineConfig({
  plugins: [palamedes(), react()],
})
```

### Vite + Solid

```bash
pnpm add @palamedes/core @palamedes/solid @palamedes/runtime @palamedes/vite-plugin
pnpm add -D @palamedes/cli vite-plugin-solid vite typescript
```

```ts
// vite.config.ts
import { defineConfig } from "vite"
import solid from "vite-plugin-solid"
import { palamedes } from "@palamedes/vite-plugin"

export default defineConfig({
  plugins: [palamedes(), solid()],
})
```

## Minimal config

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

The native `pmds` CLI discovers `palamedes.yaml`, `palamedes.yml`, `palamedes.json`, or `palamedes.toml`. Legacy `palamedes.config.ts`/`.js` files are a compatibility path read only by the JS plugin loaders via `@palamedes/config` — do not generate them for new projects.

## Minimal runtime

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

const i18n = createI18n()
setClientI18n(i18n)

export { i18n }
```

## Minimal translated code

```tsx
import { t } from "@palamedes/core/macro"

export function App() {
  return <h1>{t`Welcome to Palamedes`}</h1>
}
```

Then run:

```bash
pnpm exec pmds extract
pnpm exec pmds audit
pnpm exec pmds report
```

## Catalog workflow commands

- `pmds report --fail-if-below 90`: per-locale completeness gate for CI
- `pmds catalog merge --format=po --conflict-strategy=use-first --output out.po a.po b.po`: semantic merge of exactly two catalogs (also usable as a Git merge driver)
- `pmds catalog convert --to fcl input.po`: convert PO catalogs to the opt-in FCL format

## Recommended docs

- `/README.md`: product overview and package map
- `/docs/first-working-translation`: shortest working setup
- `/docs/configuration`: YAML-first config reference
- `/docs/cli`: full CLI reference
- `/docs/catalog-formats`: PO default and opt-in FCL
- `/docs/principles`: architectural principles
- `/docs/migrate-from-lingui`: migration guidance for Lingui-shaped projects
- `/docs/comparison-with-lingui`: positioning against Lingui
- `/docs/proof-and-benchmarks`: maturity, examples, and benchmark story
- `/examples/README.md`: verified example matrix
- `/decisions/003-source-string-first-message-identity`: source-string-first identity
- `/decisions/005-universal-geti18n-runtime-model`: runtime access model
- `/decisions/013-defer-cli-worker-parallelism-until-benchmarked-need`: why CLI workers are deferred until benchmarks justify them