React langsys-js-react

基于 langsys-js-typescript 的轻量 React 绑定,以 Hook 构建。代码中的短语既是查找键,也是基础语言的默认文本——无需键文件,也无需提取步骤。

正在使用 AI 编程智能体?把这段提示词交给它
Add Langsys translation to this React app.

1. Read https://docs.langsys.dev/llms.txt, then follow
   https://docs.langsys.dev/learn/sdk/react/ 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-react

还没有项目或密钥?快速入门两分钟即可帮你搞定。

初始化

import { LangsysApp, createLocaleStore } from 'langsys-js-react';

const locale = createLocaleStore('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,
});

读取信号

需要响应式地读取语言区域存储,或任何基础 SDK 信号(例如在 React 之外共享的存储)?useSignal(store) 会订阅并在变化时重新渲染您的组件。(Svelte 无需对应功能:这些信号原生满足其 store 约定。)

import { useSignal, useCurrentLocale } from 'langsys-js-react';

// React re-renders only on React state — it can't watch a base-SDK
// signal by itself. useSignal(signal) subscribes and re-renders on change.
function LocaleBadge() {
  const selected = useSignal(locale);   // your createLocaleStore(...)
  const loaded = useCurrentLocale();    // shortcut for the loaded locale

  return <footer>selected {selected} · loaded {loaded}</footer>;
}

交互式演练场

编辑短语和类别,以字段或原始 JSON 设置参数,然后切换语言区域,实时查看真实 SDK 的翻译效果。

示例
参数
Output

Hello, Sarah! You have 3 new messages.

const t = useT();
t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3})
t() — 组件中的内联字符串 查看源码 ↗
import { useT } from 'langsys-js-react';

function Greeting({ name }) {
  const t = useT();
  return <p>{t('Hello, {name}!', 'Greetings', { name })}</p>;
}

我该使用哪一个?

你正在翻译…… 使用 为什么
代码中的纯字符串——标签、标题或消息。包含参数;直接按平铺方式书写数量,Langsys 会生成复数形式。 useT() 返回一个字符串。代码中的短语既是查找键,也是基础语言的默认文本。
包含内联标记或动态值的一句话,保持完整。 <Phrase> 行内元素会变成中性标记,因此译者可以重新调整整句的顺序——包括标记的位置——而真实元素会在渲染时还原。
包含多个短语的一块标记区域——例如首屏横幅、页脚或卡片。 <Translate> 一个标签即可将该区域注册为单个内容块:每段文本都会被提取为独立的短语,同时保留标记结构。
绝不能翻译的内容——品牌名称、代码、ID。 <DontTranslate> 分词器和渲染器会跳过该子树;其内容保持原样,而周围的句子照常翻译。

经验法则:字符串 → useT() · 带标记的句子 → <Phrase> · 带标记的区域 → <Translate> · 不可改动的内容 → <DontTranslate>。

左侧实时渲染每个内容组件,右侧是生成它的代码。

观看 这些基础组件的演示剪辑目前放在 Svelte 页面上——接口完全相同,只是语法不同: <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).

<Translate> — content block

Welcome to our store

Browse the catalog in your language.

<Translate> — 内容块 查看源码 ↗
import { Translate } from 'langsys-js-react';

<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> — params 与标记 查看源码 ↗
import { Phrase } from 'langsys-js-react';

<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!

<DontTranslate> 查看源码 ↗
import { DontTranslate, Translate } from 'langsys-js-react';

// 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。只要你知道性别,就请传入。工作原理,以及如何找出需要它的短语 →

传入性别参数
import { useT } from 'langsys-js-react';

function LikeNotice({ user }) {
  const t = useT();
  // Pass the agreement argument alongside the value it inflects.
  return <p>{t('{username} has been invited', 'Team', {
    username: user.name,
    username_gender: user.gender, // 'male' | 'female' | 'other'
  })}</p>;
}

不知道性别?请显式传入 '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',
});
搜索文档和学习中心