React langsys-js-react

Một lớp liên kết React mỏng bao quanh langsys-js-typescript, xây dựng trên hooks. Cụm từ trong mã của bạn vừa là khóa tra cứu vừa là giá trị mặc định ở ngôn ngữ gốc — không cần tệp khóa, không cần bước trích xuất.

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.

Cài đặt

npm install langsys-js-react

Chưa có dự án hoặc khóa? Bắt đầu nhanh giúp bạn có cả hai chỉ trong hai phút.

Khởi tạo

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,
});

Đọc signal

Cần đọc kho ngôn ngữ — hoặc bất kỳ tín hiệu SDK cơ sở nào, như một store bạn chia sẻ bên ngoài React — theo cách phản ứng? useSignal(store) sẽ đăng ký theo dõi và render lại component của bạn khi có thay đổi. (Svelte không cần hàm tương đương: các signal vốn đã đáp ứng hợp đồng store của nó.)

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>;
}

Sân chơi tương tác

Chỉnh sửa cụm từ và danh mục, đặt tham số dưới dạng trường hoặc JSON thô, rồi chuyển ngôn ngữ và xem SDK thật dịch trực tiếp.

const t = useT();
t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3})

import { useT } from 'langsys-js-react';

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

Tôi nên dùng cái nào?

Quy tắc ngón tay cái: chuỗi → useT() · câu có markup → <Phrase> · vùng có markup → <Translate> · không được đụng đến → <DontTranslate>.

Mỗi thành phần nội dung được kết xuất trực tiếp ở bên trái; đoạn mã tạo ra nó ở bên phải.

Xem Hiện tại, các đoạn demo cho những thành phần cơ bản này nằm ở trang Svelte — giao diện sử dụng giống hệt nhau, chỉ khác cú pháp: <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).

import { Translate } from 'langsys-js-react';

<Translate category="Home">
  <h3>Welcome to our store</h3>
  <p>Browse the catalog in your language.</p>
</Translate>

import { Phrase } from 'langsys-js-react';

<Phrase category="Cart" params={{ name: 'Sarah', count: 3 }}>
  Hi %name%, you have %count% items in your cart.
</Phrase>

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>

Hòa hợp giới tính

Tiếng Tây Ban Nha, Pháp hay Nga biến đổi {username} has been invited theo người được nhắc đến. Langsys tạo các nhánh đó trong quá trình dịch — giống như cách tạo dạng số nhiều — và tên đối số được đặt theo tên biến, kèm thêm _gender: male, female hoặc other. Hãy truyền giá trị này bất cứ khi nào bạn biết. Cách hoạt động và cách tìm các cụm từ cần đến nó →

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>;
}

Không biết giới tính? Hãy truyền 'other' một cách tường minh — đây là nhánh trung tính. Nếu thiếu giá trị này, SDK vẫn sẽ tự động dùng nhánh other cho bạn (langsys-js-typescript 0.6.4 trở lên), nên câu vẫn hiển thị đúng. Hiện tại TypeScript từ chối username_gender trong đối tượng params viết trực tiếp (lỗi TS2353; bản sửa đang được xem xét). Cho đến khi bản sửa được phát hành, hãy tạo đối tượng params trước rồi truyền biến vào.

Kết xuất phía máy chủ

Tải danh mục bản dịch trên máy chủ rồi chuyển cho máy khách, để SDK khởi động mà không cần tải lại. SDK dịch ngay trong trình duyệt, nên HTML được render phía máy chủ vẫn ở ngôn ngữ gốc cho đến khi SDK khởi động.

// 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',
});