svintl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

svintl — i18n for Svelte

svintl — Svelte 项目的 i18n 解决方案

CLI tool for managing internationalization dictionaries with automatic translation via OpenAI.

一款用于管理国际化字典的CLI工具，支持通过OpenAI自动翻译。

Core Rule

核心规则

NEVER edit intl files directly — all

*.yaml

built.js

types.ts

in intl directories are generated. Always use

npx intl

CLI commands.

切勿直接编辑intl文件 —— intl目录下所有

*.yaml

、

built.js

、

types.ts

文件均为自动生成。请始终使用

npx intl

CLI命令进行操作。

CLI Commands

CLI 命令

bash

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 new key (errors if exists), context optional
npx intl add key.path "Value" --debug        # optional: print OpenAI request before API call
npx intl set key.path "Updated value"       # update existing key
npx intl set key.path "Value" --debug       # same (--debug on add/set)
npx intl set "mount/key.path" "Value"       # set in mount
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                          # new locale (BCP 47 tag, auto-translates)
npx intl destroy es                         # delete locale
npx intl mount foo ./any/path               # create mount
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 true                       # enable gender-aware translations
npx intl genders false                      # disable
npx intl sync en                            # re-translate all from source (EXPENSIVE — avoid)
npx intl sync en key.path                   # re-translate specific key
npx intl build                              # rebuild JS/TS from YAML

bash

npx intl hola                               # 初始化字典（默认路径：src/lib/intl/）
npx intl hola -p ./custom/path              # 在自定义路径初始化
npx intl add key.path "Value" "context"     # 添加新键（若已存在则报错），context为可选参数
npx intl add key.path "Value" --debug        # 可选：在调用API前打印OpenAI请求信息
npx intl set key.path "Updated value"       # 更新已有键值
npx intl set key.path "Value" --debug       # 同上（add/set命令均支持--debug参数）
npx intl set "mount/key.path" "Value"       # 在挂载目录中设置键值
npx intl const key.path "Same everywhere"   # 为所有语言设置相同值（不进行翻译）
npx intl unit items.count "item"            # 添加复数条目（自动生成复数形式）
npx intl move old.key new.key               # 重命名键/分支
npx intl del key.path                       # 删除键/分支
npx intl create es                          # 创建新语言（需符合BCP 47规范，自动翻译）
npx intl destroy es                         # 删除语言
npx intl mount foo ./any/path               # 创建挂载
npx intl unmount foo                        # 移除挂载（保留文件）
npx intl context "Project description"      # 设置项目级翻译指导上下文
npx intl context --clear                    # 清除项目上下文
npx intl genders true                       # 启用性别感知翻译
npx intl genders false                      # 禁用性别感知翻译
npx intl sync en                            # 从源语言重新翻译所有内容（成本高，尽量避免）
npx intl sync en key.path                   # 重新翻译指定键
npx intl build                              # 从YAML文件重新生成JS/TS文件

Dictionary Format

字典格式

YAML with arbitrary nesting, strings at leaves:

yaml

native: English
example:
  hello: "Hello world"

Usage:

{$dict.example.hello}

采用支持任意嵌套的YAML格式，叶子节点为字符串：

yaml

native: English
example:
  hello: "Hello world"

使用方式：

{$dict.example.hello}

Dynamic Values — Placeholders

动态值——占位符

For simple cases the CLI auto-generates

!js

functions from placeholder syntax — no need to write them manually:

bash

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

For complex logic, pass

!js

functions via

intl set

bash

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

Usage in components:

{$dict.greeting(user.name)}

对于简单场景，CLI会根据占位符语法自动生成

!js

函数，无需手动编写：

bash

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

对于复杂逻辑，可通过

intl set

传入

!js

函数：

bash

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

组件中使用方式：

{$dict.greeting(user.name)}

Pluralization

复数处理

Use

npx intl unit

— generates

Intl.PluralRules

-based functions:

bash

npx intl unit items.count "item"

Produces:

yaml

items:
  count:
    - one: item
      other: items

Usage:

{$dict.items.count(count)}

Complex locales (Russian, Arabic) auto-get

few

many

, etc.

使用

npx intl unit

命令——生成基于

Intl.PluralRules

的函数：

bash

npx intl unit items.count "item"

生成结果：

yaml

items:
  count:
    - one: item
      other: items

使用方式：

{$dict.items.count(count)}

复杂语言（如俄语、阿拉伯语）会自动生成

few

、

many

等复数形式。

Genders

性别感知

When enabled (

npx intl genders true

), gender-dependent phrases become functions with

gender: 'he' | 'she' | 'none'

启用后（执行

npx intl genders true

），性别相关短语会变为接收

gender: 'he' | 'she' | 'none'

参数的函数。

Mounts

挂载功能

Organize translations into separate directories:

bash

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

Mount keys use

{mount}/

prefix in CLI commands.

可将翻译内容组织到独立目录：

bash

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

在CLI命令中，挂载目录的键需使用

{mount}/

前缀。

Import Pattern

导入方式

Root dictionary:

svelte

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

Mount dictionary:

svelte

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

Mount's
intl/index.ts
:

typescript

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 }

根字典：

svelte

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

挂载字典：

svelte

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

挂载目录的
intl/index.ts
：

typescript

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 }

Context for Translation Accuracy

提升翻译准确性的上下文设置

bash

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

Context is stored in

context.yaml

and used by OpenAI when creating new locales.

bash

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

上下文信息会存储在

context.yaml

中，OpenAI创建新语言时会参考该信息。

Workflow

工作流程

Use
```
npx intl set/unit/const
```
to add/update translations
Run
```
npx intl build
```
to generate JS/TS (often auto-runs)
Import
```
dict
```
store in components
Use
```
$dict.key.path
```
in templates

使用
```
npx intl set/unit/const
```
命令添加/更新翻译内容
执行
```
npx intl build
```
生成JS/TS文件（通常会自动执行）
在组件中导入
```
dict
```
状态存储
在模板中使用
```
$dict.key.path
```
调用翻译内容

Avoid

注意事项

Direct YAML editing — always use CLI
npx intl sync
— expensive API calls, rarely needed
Non-BCP47 locale codes — must be valid tags like
```
en-US
```
,
```
es
```
,
```
pt-BR
```

禁止直接编辑YAML文件 —— 务必使用CLI操作
谨慎使用
npx intl sync
—— API调用成本高，极少需要使用
语言代码需符合BCP47规范 —— 必须是
```
en-US
```
、
```
es
```
、
```
pt-BR
```
这类有效标识