<Translate> — content block
Welcome to our store
Browse the catalog in your language.
Svelte langsys-js-svelte
基于 langsys-js-typescript 的轻量级 Svelte 5 绑定——成熟的标准绑定。基础信号已满足 Svelte 的 store 约定,因此可通过 $ store 语法读取翻译。
正在使用 AI 编程智能体?把这段提示词交给它
Add Langsys translation to this Svelte app.
1. Read https://docs.langsys.dev/llms.txt, then follow
https://docs.langsys.dev/learn/sdk/svelte/ for the install and setup.
2. The English text in the code is the translation key. Wrap user-facing
strings as they are: no keys file, no extraction step, and no
hand-written plural or gender branches (Langsys generates those).
3. Read the Langsys project id and API key from environment variables.
The write key is for development and servers only; anything shipped
to the browser gets the read-only key.
4. Keep brand names and user-generated content out of translation.安装
npm install langsys-js-svelte还没有项目或密钥？快速入门两分钟即可帮你搞定。
初始化
import { writable } from 'svelte/store';
import { LangsysApp } from 'langsys-js-svelte';
const locale = writable('en-US'); // a standard Svelte writable
await LangsysApp.init({
projectid: import.meta.env.VITE_LANGSYS_PROJECT_ID,
key: import.meta.env.VITE_LANGSYS_API_KEY, // read-only in the browser
UserLocaleStore: locale,
});交互式演练场
编辑短语和类别,以字段或原始 JSON 设置参数,然后切换语言区域,实时查看真实 SDK 的翻译效果。
示例 将
count 调到 1 再调回来——语法会随之变化。这个短语是以扁平形式编写的：Langsys 会在翻译过程中生成每种语言的复数形式（包括基础语言），SDK 则根据 count 选择对应分支。无需任何人手写 ICU。 参数
Output
Hello, Sarah! You have 3 new messages.
const value = $derived($t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3}));<script>
import { t } from 'langsys-js-svelte';
let name = 'Sarah';
</script>
<p>{$t('Hello, {name}!', 'Greetings', { name })}</p>我该使用哪一个？
| 你正在翻译…… | 使用 | 为什么 |
|---|---|---|
| 代码中的纯字符串——标签、标题或消息。包含参数;直接按平铺方式书写数量,Langsys 会生成复数形式。 | $t | 返回一个字符串。代码中的短语既是查找键,也是基础语言的默认文本。 |
| 包含内联标记或动态值的一句话,保持完整。 | <Phrase> | 行内元素会变成中性标记，因此译者可以重新调整整句的顺序——包括标记的位置——而真实元素会在渲染时还原。 |
| 包含多个短语的一块标记区域——例如首屏横幅、页脚或卡片。 | <Translate> | 一个标签即可将该区域注册为单个内容块:每段文本都会被提取为独立的短语,同时保留标记结构。 |
| 绝不能翻译的内容——品牌名称、代码、ID。 | <DontTranslate> | 分词器和渲染器会跳过该子树;其内容保持原样,而周围的句子照常翻译。 |
经验法则：字符串 → $t · 带标记的句子 → <Phrase> · 带标记的区域 → <Translate> · 不可改动的内容 → <DontTranslate>。
左侧实时渲染每个内容组件，右侧是生成它的代码——这一对的上方则是对应的演示剪辑。
<script>
import { Translate } from 'langsys-js-svelte';
</script>
<Translate category="Home">
<h3>Welcome to our store</h3>
<p>Browse the catalog in your language.</p>
</Translate><Phrase> — params & markup
Hi %name%, you have %count% items in your cart.<Phrase category="Cart" params={{ name: 'Sarah', count: 3 }}>
Hi %name%, you have %count% items in your cart.
</Phrase><DontTranslate> — never translated
Welcome! This sentence always stays in English. Thanks for visiting!
<!-- Inside a translated region, the marked span alone stays verbatim. -->
<Translate category="Tour">
<p>Welcome! <DontTranslate>This sentence always stays in English.</DontTranslate> Thanks for visiting!</p>
</Translate>性别一致
西班牙语、法语或俄语会根据所指的人对 {username} has been invited 进行屈折变化。Langsys 会在翻译时生成这些分支(与生成复数形式的方式相同),参数以变量名命名,并加上后缀 _gender:male、female 或 other。只要你知道性别,就请传入。工作原理,以及如何找出需要它的短语 →
<script>
import { t } from 'langsys-js-svelte';
export let user; // user.gender is 'male' | 'female' | 'other'
</script>
<!-- Pass the agreement argument alongside the value it inflects. -->
<p>{$t('{username} has been invited', 'Team',
{ username: user.name, username_gender: user.gender })}</p>不知道性别?请明确传入 'other'——它是中性分支。即使缺少该参数,SDK 也会自动采用 other 分支(langsys-js-typescript 0.6.4 及更高版本),因此句子仍能正确显示。
内容块
一个 <Translate> 区域会注册为一个内容块：该区块在翻译管理器中作为一个整体进行翻译和审核，但其中的每一段文本仍是独立的短语。在其他地方写出同样的句子时，会直接复用已有的译文。
<Translate category="Home">
<h3>Welcome to our store</h3>
<p>Browse the catalog in your language.</p>
<p>Free shipping on orders over $50.</p>
</Translate>分类
其他 i18n 库要求你为每个字符串都想一个键,因为同一个词可能有两种含义。在 Langsys 中,句子保留在你的代码里,由类别来完成这项工作:短语加上它的类别就是键,因此同一个词出现在两个类别中,就会对应两条翻译。
<!-- The phrase plus its category is the key. -->
<a href="/">{$t('Home', 'Main menu')}</a> <!-- es: Inicio -->
<h2>{$t('Home', 'Home repairs')}</h2> <!-- es: Hogar -->属性
如果可见文本被翻译了，而占位符、图片描述和屏幕阅读器标签仍是英文，那么表单只翻译了一半。<Translate> 会在同一次处理中覆盖这些内容：placeholder、alt、title、aria-label 和 aria-placeholder 都会随文本一同翻译，无需额外标记。任何标记为 translate="no" 的内容都会被跳过，包括其子元素。
<Translate category="Checkout">
<label>Email address</label>
<input placeholder="[email protected]" />
<img src="/lock.svg" alt="Secure checkout" />
<button aria-label="Place your order">
Place order
</button>
</Translate>数字与日期
将数字和日期作为参数传入，SDK 会遵循 CLDR（Unicode 区域数据）按当前显示的语言区域对其进行格式化：数字通过 Intl.NumberFormat 处理，Date 通过 Intl.DateTimeFormat 处理。这不仅涉及分隔符：数位分组本身就是一种形式，因此 1234567 在美式英语中是 1,234,567，而在印度英语（en-IN）中是 12,34,567。
反过来说:任何以数字形式传入的值都会被当作数量处理。订单号并不是数量,所以请将其作为字符串传入,否则德语界面会把您的订单编号显示为 1.048.576。
<script lang="ts">
import { t } from 'langsys-js-svelte';
const renewsAt = new Date(2026, 2, 14); // 14 March 2026, local time
</script>
<p>{$t('Balance: {amount}', 'Billing', { amount: 1234.5 })}</p>
<p>{$t('Renews {when}', 'Billing', { when: renewsAt })}</p>
<!-- An order number is not a quantity: pass it as a string. -->
<p>{$t('Order {ref}', 'Billing', { ref: '1048576' })}</p>服务器端渲染
在服务器端（SvelteKit）获取目录并传给客户端，这样 SDK 启动时就无需再次获取。SDK 在浏览器中进行翻译，因此在 SDK 启动之前，服务器渲染的 HTML 使用的是基础语言。
// SvelteKit: +layout.server.ts seeds the catalog, the client init reuses it.
LangsysApp.init({
projectid, key,
UserLocaleStore: locale,
initialTranslations, // fetched on the server
initialTranslationsLocale, // fetched on the server
ssrTokenStrategy: 'client',
});