Translate — content block
Welcome to our store
Browse the catalog in your language.
TypeScript langsys-js-typescript
与框架无关的基础 SDK——纯 TypeScript 或 JavaScript，无需任何框架。React、Vue 和 Svelte 的绑定都是基于此包的轻量封装；此处它直接操作 DOM。各处规则相同：代码中的短语既是查找键，也是基础语言的默认文本。
正在使用 AI 编程智能体?把这段提示词交给它
Add Langsys translation to this TypeScript app.
1. Read https://docs.langsys.dev/llms.txt, then follow
https://docs.langsys.dev/learn/sdk/typescript/ 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-typescript还没有项目或密钥？快速入门两分钟即可帮你搞定。
初始化
import { LangsysApp, createSignal } from 'langsys-js-typescript';
const locale = createSignal('en-US');
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
import { t, tSignal } from 'langsys-js-typescript';
const greeting = document.querySelector('#greeting');
const name = 'Sarah';
// tSignal re-emits a fresh t() whenever the locale or catalog
// changes — subscribe once and the element stays translated.
tSignal.subscribe(() => {
greeting.textContent = t('Hello, {name}!', 'Greetings', { name });
});我该使用哪一个？
| 你正在翻译…… | 使用 | 为什么 |
|---|---|---|
| 代码中的纯字符串——标签、标题或消息。包含参数;直接按平铺方式书写数量,Langsys 会生成复数形式。 | t() | 返回一个字符串。代码中的短语既是查找键,也是基础语言的默认文本。 |
| 包含内联标记或动态值的一句话,保持完整。 | Phrase | 行内元素会变成中性标记，因此译者可以重新调整整句的顺序——包括标记的位置——而真实元素会在渲染时还原。 |
| 包含多个短语的一块标记区域——例如首屏横幅、页脚或卡片。 | Translate | 一个标签即可将该区域注册为单个内容块:每段文本都会被提取为独立的短语,同时保留标记结构。 |
| 绝不能翻译的内容——品牌名称、代码、ID。 | translate="no" | 分词器和渲染器会跳过该子树;其内容保持原样,而周围的句子照常翻译。 |
经验法则：字符串 → t() · 带标记的句子 → Phrase · 带标记的区域 → Translate · 不可改动的内容 → translate="no"。
左侧实时运行每个原生 DOM 处理程序,右侧是对应的接入代码。
观看 这些基础组件的演示剪辑目前放在 Svelte 页面上——接口完全相同，只是语法不同： <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).
import { Translate } from 'langsys-js-typescript';
// <section id="hero">
// <h3>Welcome to our store</h3>
// <p>Browse the catalog in your language.</p>
// </section>
new Translate(document.querySelector('#hero'), { category: 'Home' });Phrase — params & markup
Hi {name}, you have {count} items in your cart.
import { Phrase } from 'langsys-js-typescript';
// <p id="cart-note">Hi {name}, you have {count} items in your cart.</p>
new Phrase(document.querySelector('#cart-note'), {
category: 'Cart',
params: { name: 'Sarah', count: 3 },
});translate="no" — never translated
Welcome! This sentence always stays in English. Thanks for visiting!
// The standard translate="no" attribute — the tokenizer
// and renderer skip the subtree, so it stays verbatim while
// the sentence around it translates.
// <p id="signin">Welcome! <span translate="no">This sentence always stays in English.</span> Thanks for visiting!</p>
new Translate(document.querySelector('#signin'), { category: 'Tour' });性别一致
西班牙语、法语或俄语会根据所指的人对 {username} has been invited 进行屈折变化。Langsys 会在翻译时生成这些分支(与生成复数形式的方式相同),参数以变量名命名,并加上后缀 _gender:male、female 或 other。只要你知道性别,就请传入。工作原理,以及如何找出需要它的短语 →
import { t } from 'langsys-js-typescript';
// Pass the agreement argument alongside the value it inflects.
t('{username} has been invited', 'Team', {
username: user.name,
username_gender: user.gender, // 'male' | 'female' | 'other'
});不知道性别?请显式传入 'other'——它是中性分支。即使缺失,SDK 也会自动为您采用 other 分支(langsys-js-typescript 0.6.4 及更高版本),因此句子仍能正确显示。目前,TypeScript 会拒绝内联参数对象中的 username_gender(错误 TS2353;修复程序正在审核中)。在修复上线之前,请先构建参数对象,再传入该变量。
服务器端渲染
在服务器上获取目录并将其传递给客户端，这样 SDK 启动时就无需再次获取。SDK 在浏览器中进行翻译，因此在 SDK 启动之前，服务器渲染的 HTML 使用的是基础语言。
// The server fetches the catalog; the client init starts from it
// instead of fetching it again, and translates once it runs.
LangsysApp.init({
projectid, key,
UserLocaleStore: locale,
initialTranslations, // fetched on the server
initialTranslationsLocale, // fetched on the server
ssrTokenStrategy: 'client',
});