/yapyak

name: yapyak
description: "yapyak, an i18n compiler with a small runtime: t() with the source string as the key, ICU plurals and selects, rich text, format.* for numbers, dates and lists, locale switching and persistence, yapyak.config.ts, translators, the yapyak CLI, and YAPnnnn diagnostics. Use when adding or editing user-facing text in a project that depends on yapyak, when setting up @yapyak/vite, @yapyak/react, @yapyak/vue, @yapyak/svelte, @yapyak/astro, @yapyak/nuxt, @yapyak/react-router, @yapyak/sveltekit or @yapyak/tanstack-start, or when a YAP diagnostic fires."
license: MIT
metadata:
  source: https://github.com/yapyak/yapyak/tree/main/skills/yapyak

yapyak compiles `t('Save changes')` into the module that renders it. The source string is the key. On save, the yapyak plugin extracts every `t()` call, writes an empty stub to each locale file, and fills the stub through a translator when one is configured.

Read the reference for the project's framework before writing setup or component code:

| Framework | Reference | | --- | --- | | React with Vite | [references/react.md](references/react.md) | | React Router | [references/react-router.md](references/react-router.md) | | TanStack Start | [references/tanstack-start.md](references/tanstack-start.md) | | Vue with Vite | [references/vue.md](references/vue.md) | | Nuxt | [references/nuxt.md](references/nuxt.md) | | Svelte with Vite | [references/svelte.md](references/svelte.md) | | SvelteKit | [references/sveltekit.md](references/sveltekit.md) | | Astro | [references/astro.md](references/astro.md) |

Every `YAPnnnn` diagnostic, its cause, and its fix: [references/diagnostics.md](references/diagnostics.md)

Install

Requirements: Node.js 22.23.4+, Vite 8+. Frameworks: React 19+, Vue 3.4+, Svelte 5+, Astro 7+, Nuxt 4.1+, React Router 7.9+, SvelteKit 3+, TanStack Start 1.168+.

| Framework | Install | Build config | Processor | | --- | --- | --- | --- | | React | `npm install yapyak @yapyak/vite @yapyak/react` | `plugins: [react(), yapyak()]` | `react()` from `@yapyak/react/processor` | | React Router | add `@yapyak/react-router` | `plugins: [reactRouter(), yapyak()]` | `react()` | | TanStack Start | add `@yapyak/tanstack-start` | `plugins: [tanstackStart(), react(), yapyak()]` | `react()` | | Vue | `npm install yapyak @yapyak/vite @yapyak/vue` | `plugins: [vue(), yapyak()]` | `vue()` from `@yapyak/vue/processor` | | Nuxt | `npx nuxi module add yapyak` | `modules: ['@yapyak/nuxt']` | `nuxt()` from `@yapyak/nuxt/processor` | | Svelte | `npm install yapyak @yapyak/vite @yapyak/svelte` | `plugins: [svelte(), yapyak()]` | `svelte()` from `@yapyak/svelte/processor` | | SvelteKit | add `@yapyak/sveltekit` | `plugins: [sveltekit(), yapyak()]` | `svelte()` | | Astro | `npm install yapyak @yapyak/astro` | `integrations: [yapyak()]` from `@yapyak/astro/integration` | `astro()` from `@yapyak/astro/processor` |

Steps, in order:

1. Install the packages. Add a translator package when the project translates with a model: `@yapyak/anthropic`, `@yapyak/openai`, `@yapyak/gemini`, `@yapyak/ollama`, or `@yapyak/claude-code`. 2. Register the plugin in the build config, after the framework plugin. `yapyak` is a named export of `@yapyak/vite`. 3. Create `yapyak.config.ts` at the project root with the processor for the framework:

import { defineConfig } from 'yapyak/config';
import { react } from '@yapyak/react/processor';

export default defineConfig({
  processors: [react()]
});

4. Add `.yapyak/types.d.ts` and `yapyak.config.ts` to `include` in `tsconfig.json`. Nuxt adds the types on its own. 5. Add the first target locale: `npx yapyak add sv`. This creates `locales/sv.json` and regenerates the `Locale` type. 6. Add `.yapyak/` to `.gitignore`. It holds the orphan cache; the locale files are the committed source of truth.

Register one processor per framework in the project. The built-in parser reads `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.mjs`, `.cts`, and `.cjs` without one.

Writing text

Wrap every user-facing string in `t()` from `yapyak`. Write the sentence in the source language exactly as the reader sees it; it is the key.

// ✓ The sentence is the key
t('Save changes');

// ✗ A synthetic key has no source string to translate
t('common.buttons.save');

Call `t()` inside the component or function that renders the text. A module-scope call evaluates once and never follows the active locale (`YAP0055`).

// ✓ Reads the active locale on every render
function SaveButton() {
  return t('Save changes');
}

// ✗ Evaluates once when the module loads
const label = t('Save changes');

Write the source as a static string literal and the params as an inline object literal. The compiler reads neither from a variable.

// ✓ Static source, inline params
t('Hi {name}', { name });

// ✗ Template literal (YAP0002)
t(`Hi ${name}`);

// ✗ Variable source
t(label);

// ✗ Params in a variable (YAP0006)
t('Hi {name}', params);

Never concatenate around `t()` → put the moving part in a placeholder.

// ✓ One message, one placeholder
t('{count} items in your cart', { count });

// ✗ Word order differs per language
t('You have') + ' ' + count + ' ' + t('items');

Call `t()` in attribute positions too: `aria-label={t('Pause')}`, `:title="t('Settings')"`, `placeholder={t('Search')}`. The attribute name is part of the call-site context the translator receives.

Placeholders

Write `{name}` in the source and pass the value under the same name. TypeScript derives the required keys from the source string.

| Form | Example | Value type | | --- | --- | --- | | Plain | `t('Hi {name}', { name })` | `string \| number`, rendered as its string form | | Number | `t('Total {n, number, integer}', { n })` | `number`; styles `decimal`, `integer`, `percent`, `currency <ISO 4217>` | | Date | `t('Updated {when, date, long}', { when })` | `Date` or millisecond timestamp; styles `short`, `medium`, `long`, `fu