svintl

svintl — Svelte 国际化

用于管理国际化词典的 CLI 工具，可通过 OpenAI 自动翻译。

核心规则

intl 目录中的 *.yaml、built.js 和 types.ts 文件均为生成文件——应通过 npx intl CLI 编辑，而非手动编辑。

CLI 命令

npx intl hola                               # init dictionaries (default: src/lib/intl/)
npx intl hola -p ./custom/path              # init at custom path
npx intl add key.path "Value" "context"     # add a new key — fails if it already exists; context optional
npx intl set key.path "Updated value"       # update a key that already exists — fails if missing
npx intl set "mount/key.path" "Value"       # target a mount with the mount/ prefix
npx intl add --from strings.yaml            # many new keys in one run — `key: value` or `key: { value, context }`, flat (`a.b: …`) or nested (`a: { b: … }`)
npx intl set --from strings.yaml            # many existing keys in one run; `--from -` reads stdin
npx intl add key.path "Value" --debug       # --debug (add or set): print the OpenAI request first
npx intl create de --tokens 60000           # --tokens (any command): output-token limit per OpenAI request, default 30000
npx intl const key.path "Same everywhere"   # same value across all locales (no translation)
npx intl unit items.count "item"            # pluralized entry (auto-generates plural forms)
npx intl move old.key new.key               # rename key/branch
npx intl del key.path                       # delete key/branch
npx intl create es                          # add a locale (BCP 47 tag) — auto-translates the whole dictionary into it
npx intl destroy es -y                      # delete locale (without -y it fails)
npx intl mount foo ./any/path               # create empty mount
npx intl import foo ./any/path              # adopt existing dict dir as mount, reconcile locales
npx intl unmount foo                        # remove mount (keeps files)
npx intl context "Project description"      # set project-wide translation guidance
npx intl context --clear                    # clear project context
npx intl genders he she none                # enable gender-aware translations (list the gender values)
npx intl genders                            # print current gender values
npx intl sync en key.path                   # reconcile: re-translate one key into all locales from source en
npx intl sync en                            # reconcile: re-translate the whole dictionary from source en
npx intl build                              # rebuild JS/TS from YAML

词典格式

使用 YAML，支持任意嵌套结构，叶节点为字符串：

native: English
example:
  hello: "Hello world"

用法：{$dict.example.hello}

动态值 — 占位符

对于简单情况，CLI 会根据占位符语法自动生成 !js 函数——无需手动编写：

npx intl set greeting "Hello, {name}!"            # {name} → function param
npx intl set joined "[names] joined {groupName}"  # [names] → Intl.ListFormat

对于复杂逻辑，请通过 intl set 传入 !js 函数：

npx intl set greeting '!js (count) => `${count || "No"} item${count === 1 ? "" : "s"}`'

在组件中用法：{$dict.greeting(user.name)}

将整句话保留在词典中。 切勿在模板中把句子拆开，并将动态值夹在中间：

<strong>{brand}</strong>{$dict.form.destroyDescription}


{@html $dict.form.destroyDescription(brand)}

npx intl set "apps/form.destroyDescription" \
  '!js (brand) => `<strong>${brand}</strong> and all accumulated data will be permanently deleted.`'

如果名称需要标记，且在各种语言中始终位于句首，请将标签放在 !js 函数内，并使用 {@html} 渲染——传入用户控制的值前，请先进行转义。

复数形式

使用 npx intl unit——生成基于 Intl.PluralRules 的函数：

npx intl unit items.count "item"

生成结果：

items:
  count:
    - one: item
      other: items

用法：{$dict.items.count(count)}

对于复杂的语言区域设置（俄语、阿拉伯语），会自动生成 few、many 等形式。

性别

启用后（npx intl genders he she none），依赖性别的短语会变成函数，其最后一个参数为性别（'he' | 'she' | 'none'）——短语自身的参数放在前面，例如 (name, gender) => …。列出的值将成为生成的 Grammar 联合类型。

挂载

将翻译整理到不同目录中：

npx intl mount admin ./src/features/admin/intl
npx intl set "admin/dashboard.title" "Admin Dashboard"

挂载键在 CLI 命令中使用 {mount}/ 前缀。

mount 会创建一个空挂载；import 会导入已有内容的目录（其中包含自己的 context.yaml），并使其语言区域设置与根目录一致——删除根目录不支持的语言，生成根目录缺少的语言（翻译导入的 inputs），共享的语言区域设置则保持不变。

导入模式

根词典：

<script lang="ts">
  import { dict, locale } from '$lib/intl'
</script>
<h1>{$dict.example.hello}</h1>

挂载词典：

<script lang="ts">
  import { dict } from './intl'
</script>
<h1>{$dict.dashboard.title}</h1>

挂载的 intl/index.ts（当 package.json 映射了 #lib/* 时，例如 SvelteKit 3，应使用 #lib/intl/index.js 而非 $lib/intl；mount 和 import 会在此处写入相应形式，build 则会将其写入 built.js）：

import { derived } from 'svelte/store'
import { locale } from '$lib/intl'
import { dictionaries } from './built.js'
import type { Locale, Dictionary } from './types'

const dict = derived(locale, ($locale) => dictionaries[$locale])
export { dict, dictionaries, locale }
export type { Locale, Dictionary }

提升翻译准确性的上下文

npx intl set app.welcome "Welcome" "greeting shown on homepage"
npx intl context "B2B SaaS for enterprise users"

上下文存储在 context.yaml 中，OpenAI 创建新的语言区域设置时会使用它。

工作流

1. 使用 npx intl add/set/unit/const 添加或更新翻译——多个键应放在同一个 add --from / set --from 文件中，切勿循环调用 npx intl
2. 运行 npx intl build 生成 JS/TS（通常会自动运行）
3. 在组件中导入 dict store
4. 在模板中使用 $dict.key.path

避免

• 手动编辑 YAML——请通过 CLI 操作
• 循环调用 npx intl——每次调用都会启动一个进程、发起翻译请求并执行构建；请将键写入文件，然后运行一次 add --from
• 使用 const + sync 批量添加——sync 会重新翻译整个词典；请使用 add --from
• 日常编辑时使用 npx intl sync——它仅用于手动编辑源文件后进行协调；请改用 add / set
• 使用非 BCP47 语言区域设置代码——请使用有效标签，例如 en-US、es、pt-BR
• 在模板中拆分短语——不要将动态值与词典中的后缀或前缀拼接；请用一个 {placeholder} / !js 条目表示完整句子