yapyak
Original:🇺🇸 English
Translated
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.
9installs
Sourceonmax/nuxt-skills
Added on
NPX Install
npx skill4agent add onmax/nuxt-skills yapyakTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →yapyak compiles into the module that renders it. The source string is the key. On save, the yapyak plugin extracts every call, writes an empty stub to each locale file, and fills the stub through a translator when one is configured.
t('Save changes')t()Read the reference for the project's framework before writing setup or component code:
| Framework | Reference |
|---|---|
| React with Vite | references/react.md |
| React Router | references/react-router.md |
| TanStack Start | references/tanstack-start.md |
| Vue with Vite | references/vue.md |
| Nuxt | references/nuxt.md |
| Svelte with Vite | references/svelte.md |
| SvelteKit | references/sveltekit.md |
| Astro | references/astro.md |
Every diagnostic, its cause, and its fix: references/diagnostics.md
YAPnnnnInstall
Requirements: Node.js 22.22+, 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 | | | |
| React Router | add | | |
| TanStack Start | add | | |
| Vue | | | |
| Nuxt | | | |
| Svelte | | | |
| SvelteKit | add | | |
| Astro | | | |
Steps, in order:
- Install the packages. Add a translator package when the project translates with a model: ,
@yapyak/anthropic,@yapyak/openai,@yapyak/gemini, or@yapyak/ollama.@yapyak/claude-code - Register the plugin in the build config, after the framework plugin. is a named export of
yapyak.@yapyak/vite - Create at the project root with the processor for the framework:
yapyak.config.ts
ts
import { defineConfig } from 'yapyak/config';
import { react } from '@yapyak/react/processor';
export default defineConfig({
processors: [react()]
});- Add and
.yapyak/types.d.tstoyapyak.config.tsininclude. Nuxt adds the types on its own.tsconfig.json - Add the first target locale: . This creates
npx yapyak add svand regenerates thelocales/sv.jsontype.Locale - Add to
.yapyak/. It holds the orphan cache; the locale files are the committed source of truth..gitignore
Register one processor per framework in the project. The built-in parser reads , , , , , , , and without one.
.ts.tsx.js.jsx.mts.mjs.cts.cjsWriting text
Wrap every user-facing string in from . Write the sentence in the source language exactly as the reader sees it; it is the key.
t()yapyakts
// ✓ The sentence is the key
t('Save changes');
// ✗ A synthetic key has no source string to translate
t('common.buttons.save');Call inside the component or function that renders the text. A module-scope call evaluates once and never follows the active locale ().
t()YAP0055ts
// ✓ 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.
ts
// ✓ 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 → put the moving part in a placeholder.
t()ts
// ✓ One message, one placeholder
t('{count} items in your cart', { count });
// ✗ Word order differs per language
t('You have') + ' ' + count + ' ' + t('items');Call in attribute positions too: , , . The attribute name is part of the call-site context the translator receives.
t()aria-label={t('Pause')}:title="t('Settings')"placeholder={t('Search')}Placeholders
Write in the source and pass the value under the same name. TypeScript derives the required keys from the source string.
{name}| Form | Example | Value type |
|---|---|---|
| Plain | | |
| Number | | |
| Date | | |
| Time | | |
| Plural | | |
| Ordinal | | |
| Select | | |
Name a placeholder with letters, digits, and underscores, starting with a letter or underscore (). Non-ASCII letters are allowed.
YAP0052Rules for , , and :
pluralselectordinalselect- Write an branch (
other).YAP0008 - Write inside a plural branch for the formatted count.
# - Write ,
=0for an exact value; exact matches are tried before categories.=1 - Name plural branches with the CLDR keywords ,
zero,one,two,few,many(other).YAP0046 - Write only the branches the source language uses, and
onefor English; the translator adds the branches each target locale needs.other - Nest freely: a branch is a full message and holds placeholders, plurals, and selects.
- Split a message that has become unreadable into two calls and let the component pick.
t() - Type a value as a union literal so every legal value has a branch.
select
Format a list with outside the message and pass the result in as a placeholder. Format relative time with outside the message.
format.list()format.relativeTime()Homonyms
Split two calls with the same source and different meanings with :
t.as(context, source)ts
t.as('action', 'Open');
t.as('status', 'Open');- Write the context as a short literal label (,
action,status,noun), never a variable (verb).YAP0017 - Use for every occurrence of that source in the source file. Mixing
t.as()andt('Open')in one file is an error (t.as('action', 'Open')).YAP0018 - Use plain when the source has one meaning. A lone context is an error (
t()).YAP0019
Forced locale
- Write for the translation in a forced locale regardless of the active one. The locale argument is typed against
t.in(locale, source).Locale - Chain or
t.in('sv').as('action', 'Open')when both apply.t.as('action').in('sv', 'Open') - Complete the chain in one expression. A chain stored in a variable is an error ().
YAP0020
Rich text
Write tags inside the source and bind each tag to a handler in from the framework's adapter package.
<RichText>ts
t('Read our <link>privacy policy</link> for details.');
t('Line one<br/>line two');| Tag | Form | Handler |
|---|---|---|
| Pair | | Receives the wrapped children |
| Void | | Receives nothing |
- Start a tag name with a letter and continue with letters or digits.
- Name a tag by meaning (,
link,strong), never by HTML element; the element belongs in the handler.price - Bind a handler for every tag in the source.
- Never write attributes on a tag → put the in the handler.
href - Walk the structure with from
parseRichText(value), which returnsyapyak, whenRichTextNode[]does not fit.<RichText>
Take the handler shape from the framework's reference file.
Formatting outside messages
Format values outside a message with from . Every call reads the active locale.
formatyapyak| Method | Backed by | Note |
|---|---|---|
| | |
| | |
| | Run each item through |
| | Negative is past; |
| | |
| Returns a |
- Use for a value outside a message and an ICU sub-format for a value inside one.
format.* - Type a currency code as from
Currency; narrow user input withyapyak.isCurrency(value) - Label a locale switcher with , never with a
format.in(value).displayName(value, 'language')call per language.t() - An unsupported currency, unit, time zone, or display-name code renders a fallback instead of throwing and reports ,
YAP0035,YAP0036, orYAP0037.YAP0056
The active locale
A locale is the BCP 47 tag of a file in : for , for . Write tags as (). The type is the union of the files on disk and refreshes on .
localesDirsvlocales/sv.jsonen-GBlocales/en-GB.jsonlowercase-Titlecase-UPPERCASEzh-Hant-TWLocaleyapyak addThe active locale resolves in this order, first value wins: a persisted choice, a detected locale when is on, then .
detectUserLocaledefaultLocaleExport from | Use |
|---|---|
| The active locale, outside components |
| Switch and persist; ignored with a warning for an unknown value ( |
| Every added locale, for a switcher |
| The locale when no persisted or detected locale matches |
| Type guard for a canonical string |
| Normalizes casing, returns |
| |
| |
Read and switch the locale inside a component through the framework binding; never call or there.
getLocale()setLocale()| Framework | Binding |
|---|---|
| React | |
| Vue, Nuxt | |
| Svelte, SvelteKit | |
| Astro | |
Narrow a string from a URL, a form, or a cookie with or before .
isLocale()parseLocale()setLocale()yapyak.config.ts
yapyak.config.tsEvery field is optional. Export the result of from .
defineConfigyapyak/config| Field | Default | Sets |
|---|---|---|
| | The language the source strings are written in. Set it only when it differs from |
| | The locale when no persisted or detected locale matches |
| | The directory of locale files, relative to the project root |
| | Directories, globs, or |
| tests, | Files to skip; replaces the default. Extend with |
| | One per framework |
| none | The translator that fills stubs |
| | New strings in one save above which the save loop writes stubs but skips the translator. |
| | Keep the translation when a source string is edited in place |
| | Where the active locale is stored between page loads |
| | Match |
| | Keep |
| Processor | Option | Use |
|---|---|---|
| | React Server Components: only |
| | Another global |
| none |
Persistence
| Value | Options | Fits |
|---|---|---|
| Kiosk, development build, locale carried by another system. A reload returns to | |
| | SSR apps. The adapter reads the cookie per request; |
| | Client-only apps. Under SSR the first render uses |
| | Locale in the path ( |
- Under , switch by navigating.
'url'is a no-op and reportssetLocale().YAP0026 - Set on the cookie in production only; on plain HTTP the browser refuses the write.
secure: true
Fixed-locale builds
- Set in the build config, never in
fixedLocale. Everyyapyak.config.tscompiles to the literal of that locale and the runtime disappears from the bundle.t() - Drive a CI matrix from an environment variable. With the variable unset, the build is a normal multi-locale build.
- Pass an added locale; the build throws otherwise.
| Framework | Where |
|---|---|
| Vite (React, Vue, Svelte, React Router, SvelteKit, TanStack Start) | |
| Astro | |
| Nuxt | |
Locale files
One JSON file per target locale in . The source language has no file. Entries nest under the source file's path, then the source string:
localesDirjson
{
"src/components/save-button.tsx": {
"Save changes": "Spara ändringar"
}
}A homonym nests its contexts under the source:
json
{
"src/components/dialog.tsx": {
"Open": {
"action": "Öppna",
"status": "Öppen"
}
}
}- An empty string is an empty stub. The runtime renders the source string for it.
- Hand-edit a value to correct or replace a translation. The running app updates through HMR.
- Keep every placeholder, tag, and ICU structure of the source in the translation (,
YAP0010,YAP0011,YAP0012,YAP0038,YAP0045,YAP0050). Placeholder names stay fixed; their position in the sentence is free.YAP0051 - Never edit a key → change the source string in the component; the compiler rewrites the key.
- Never add an entry by hand → write the call; the save loop or
t()creates the stub.yapyak translate - Renames and moves of source files restore translations from the orphan cache in on the next save. Deleting
.yapyak/orphans.jsonloses nothing committed..yapyak/ - Orphans stay in the locale file until removes them.
yapyak clean --write
Fill empty stubs by hand only when the project has no translator or the user asks for it.
Translators
A translator fills empty stubs on save and in . Requests go from the developer's machine to the provider. Set one in :
yapyak translateyapyak.config.tsts
import { defineConfig } from 'yapyak/config';
import { anthropic } from '@yapyak/anthropic';
export default defineConfig({
translator: anthropic({
apiKey: process.env.ANTHROPIC_API_KEY,
glossary: { cart: { sv: 'kundvagn' } },
voice: 'Concise and friendly'
})
});| Package | Factory | Key | Defaults that differ |
|---|---|---|---|
| | | |
| | | Extras |
| | | |
| | none | |
| | the signed-in | |
| Shared option | Default | Sets |
|---|---|---|
| per provider | Model identifier |
| none | One or two sentences of tone guidance |
| | |
| | |
| | Existing translations sent per request as style reference |
| | Sampling temperature |
| per provider | Output token cap |
| | Per-request timeout in milliseconds |
| | Retries on 408, 429, 5xx, and network failures |
| | Source strings per request |
| | Parallel requests |
| | Extra HTTP headers |
| per provider | API URL |
- The context is sent at every
t.as()level.context - A voice or glossary change affects new translations only. Run or
yapyak translate --forceto propagate it.yapyak retranslate "<source>" - Pick the translator by environment when CI has no signed-in CLI: .
process.env.CI ? anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }) : claudeCode()
A custom translator is from :
createTranslator({ id, translate })yapyak/translator- returns one object per item, in item order, keyed by every target locale.
translate({ items, signal, sourceLocale, targetLocales }) - Forward to the request.
signal - Throw ,
TranslatorAuthError,TranslatorRateLimitError,TranslatorTimeoutError,TranslatorNetworkError,TranslatorSafetyError, orTranslatorInvalidResponseErrorfromTranslatorTruncatedError.yapyak/translator - Retry inside the callback. yapyak runs it once.
CLI
Run through the package manager: , , . Every command except walks the source files first, so a call added without the dev server running is still found.
npx yapyak <command>pnpm yapyak <command>bunx yapyak <command>infot()| Command | Does | Exit code |
|---|---|---|
| Creates the locale file, fills it through the translator, regenerates the | non-zero on an unrecognized tag |
| Fills empty stubs. | |
| Re-translates one source string; the flags compose | |
| Coverage per locale | |
| Missing translations, compile-time diagnostics, ICU mismatches | |
| Lists orphans; | |
| Snapshot keyed by locale, then path, then source | non-zero on an unknown tag |
| Versions for a bug report | |
Boolean flags accept : . and strip color.
=--write=falseNO_COLORCICI order: with the provider key in the environment, then , then the build. never calls the translator.
yapyak translateyapyak checkcheckWorking in a project
- Write the call in the component. With the dev server running, the save writes the stub and the translator fills it. Without it, the CLI finds the call.
t() - Run before finishing. Fix every reported
npx yapyak checkwith references/diagnostics.md.YAPnnnn - Run when
npx yapyak translatereports missing translations and the project has a translator. Fill the stubs by hand when it has none.check - Commit the locale files with the code. They are the source of truth; is a cache.
.yapyak/ - Run after removing components, and
npx yapyak cleanonce the list is right.--write
Diagnostics an agent most often triggers:
| Code | Cause | Fix |
|---|---|---|
| Template literal source | |
| Params do not match the placeholders | Match the keys to the |
| Params in a variable | Inline object literal |
| No | Add |
| | |
| Chain stored in a variable | Complete |
| Branch name is not a CLDR keyword | |
| | Move the call into the function that renders it |
| | Register the SSR adapter from the framework reference |