yapyak 是一个 i18n 编译器,运行时体积较小。它的核心设计是把源字符串本身当作键:调用 t('Save changes') 时,编译器会把这条消息编译进渲染它的模块。保存文件时,yapyak 插件会提取所有 t() 调用,向每个语言文件写入空占位,并在配置了翻译器时通过翻译器填充这些占位。
框架支持与安装 项目为每个框架提供了参考文档,包括 React with Vite、React Router、TanStack Start、Vue with Vite、Nuxt、Svelte with Vite、SvelteKit 和 Astro。环境要求为 Node.js 22.22+、Vite 8+;框架版本要求为 React 19+、Vue 3.4+、Svelte 5+、Astro 7+、Nuxt 4.1+、React Router 7.9+、SvelteKit 3+、TanStack Start 1.168+。
以 React 为例,安装 yapyak、@yapyak/vite、@yapyak/react,在构建配置中于框架插件之后注册 yapyak() 插件,在项目根目录创建 yapyak.config.ts 并指定处理器,将 .yapyak/types.d.ts 与 yapyak.config.ts 加入 tsconfig.json 的 include,执行 npx yapyak add sv 添加首个目标语言并生成 locales/sv.json 与 Locale 类型,最后把 .yapyak/ 加入 .gitignore。Nuxt 通过 npx nuxi module add yapyak 添加模块,且会自动添加类型。内置解析器可直接读取 .ts、.tsx、.js、.jsx、.mts、.mjs、.cts、.cjs 文件。
文本编写规则 每条面向用户的字符串都应包裹在 t() 中,并按用户看到的原文书写,原文即键;不要使用 common.buttons.save 这类合成键。t() 应在渲染该文本的组件或函数内部调用,模块作用域调用只会求值一次,不会跟随当前语言变化。源文本须为静态字符串字面量,参数须为内联对象字面量,编译器不从变量读取。不要在 t() 周围拼接字符串,而应把变化部分放进占位符。t() 也可用于属性位置,如 aria-label、:title、placeholder。
占位符 占位符以 {name} 书写并按同名传入值,TypeScript 会从源字符串推导必需键。支持形式包括:普通占位符、数字(decimal、integer、percent、currency 样式)、日期与时间(short、medium、long、full 样式)、复数、序数和 select。复数、序数和 select 必须包含 other 分支;复数分支内用 # 表示格式化后的计数;可用 =0、=1 表示精确值,精确匹配优先于类别;分支名须使用 CLDR 关键字。只写源语言使用的分支,由翻译器补充目标语言所需分支。分支可自由嵌套。列表与相对时间应在消息外使用 format.list() 和 format.relativeTime() 格式化后再作为占位符传入。
同名异义、强制语言与富文本 同源不同义的消息用 t.as(context, source) 区分,context 须为短字面量标签,同一源文件中每次出现都须使用 t.as()。t.in(locale, source) 用于获取指定语言的译文,可与 as 链式组合,且须在一个表达式中完成。富文本在源字符串中写标签,并在框架适配包提供的 <RichText> 中为每个标签绑定处理函数;标签按语义命名,不写属性,href 等放在处理函数中。无法使用 <RichText> 时可用 parseRichText(value) 遍历结构。
消息外格式化 format 对象提供 number、dateTime、list、relativeTime、displayName 以及 format.in(locale),分别基于 Intl 对应 API。货币代码可用 Currency 类型与 isCurrency() 校验。不受支持的货币、单位、时区或显示名称代码会渲染回退值并报告对应诊断。
活动语言 语言为 localesDir 中文件的 BCP 47 标签。活动语言的解析顺序为:持久化的选择、开启 detectUserLocale 时的检测结果、defaultLocale。yapyak 导出 getLocale()、setLocale()、locales、defaultLocale、isLocale()、parseLocale()、getLocaleFallbackChain()、getTextDirection() 等;组件内应通过框架绑定读取和切换语言(React 用 useLocale()、useTextDirection();Vue/Nuxt 用 locale、textDirection ref;Svelte 用 locale.current;Astro 在 frontmatter 中用 getLocale())。从 URL、表单或 Cookie 取得的字符串应先经 isLocale() 或 parseLocale() 收窄。
配置 所有字段可选:sourceLocale 默认等于 defaultLocale;defaultLocale 默认 'en';localesDir 默认 'locales';include 默认 ['.'];exclude 有默认列表可扩展;processors 每个框架一个;translator 默认为无;autoTranslateThreshold 默认 20;preserveTranslationsOnSourceEdit 在无翻译器时默认 true;persistence 默认 'none';detectUserLocale 默认 false;syncHtmlAttributes 默认 false。处理器支持 react({ rsc: true }) 与 nuxt({ explicitImports: true }) 等选项。
持久化策略 'none' 适合 kiosk 或开发构建;'cookie' 适合 SSR 应用,可在服务端读取并缓冲 Set-Cookie;'local-storage' 适合纯客户端应用,SSR 下首屏使用 defaultLocale;'url' 从路径或查询串读取语言,切换需导航,setLocale() 为空操作。cookie 的 secure: true 仅应在生产环境启用。
固定语言构建 fixedLocale 须设在构建配置而非 yapyak.config.ts 中。设置后每个 t() 都编译为该语言的字面量,运行时从包中消失,可用于由环境变量驱动的 CI 矩阵;传入未添加的语言时构建会报错。
语言文件 每个目标语言一个 JSON 文件,按源文件路径和源字符串嵌套,空字符串表示空占位,运行时渲染源字符串。可手工修正译文并通过 HMR 生效。译文须保留源字符串的全部占位符、标签与 ICU 结构,占位符名称固定但位置可自由调整。不要编辑键,也不要手工新增条目;源文件重命名或移动后,下次保存会从 .yapyak/orphans.json 的孤立缓存恢复译文;孤立条目需通过 yapyak clean --write 删除。
翻译器 翻译器在保存时和 yapyak translate 时填充空占位,请求从开发机发往提供商。可选 @yapyak/anthropic、@yapyak/openai、@yapyak/gemini、@yapyak/ollama、@yapyak/claude-code,各自有默认密钥环境变量或端点,OpenAI 兼容端点可通过 endpoint 与 headers 指定。共享选项包括 model、voice(语气指导)、glossary(按源词和目标语言的术语表)、context('none' 只发源字符串,'rich' 附带周边代码)和 examples。
适用场景与限制 适用于希望在源码中以自然语言原文作为键、需要 ICU 复数与富文本、并希望自动提取与翻译的 React、Vue、Nuxt、Svelte、Astro 等项目。限制包括:源文本必须是静态字面量,参数必须是内联对象;t() 不能放在模块作用域;固定语言构建下运行时被移除;'url' 持久化下 setLocale() 无效;项目未提供定价、性能基准、浏览器兼容范围或翻译质量的量化说明,暂未提供。