TypeScript langsys-js-typescript

SDK nền tảng không phụ thuộc framework — TypeScript hoặc JavaScript thuần, không cần framework. Các bản liên kết React, Vue và Svelte chỉ là lớp bao mỏng bên ngoài gói này; ở đây nó điều khiển trực tiếp DOM. Quy tắc giống nhau ở mọi nơi: 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 bằng ngôn ngữ gốc.

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.

Cài đặt

npm install langsys-js-typescript

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

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.

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

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

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

Mỗi trình xử lý DOM thuần chạy trực tiếp ở bên trái; đoạn mã kết nối 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-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' });

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

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

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

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