Svelte langsys-js-svelte

Một lớp liên kết Svelte 5 mỏng bên trên langsys-js-typescript — bản liên kết chuẩn và đã hoàn thiện. Các signal cơ sở vốn đã đáp ứng store contract của Svelte, nên bản dịch được đọc bằng cú pháp store $.

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.

Cài đặt

npm install langsys-js-svelte

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

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

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 → <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 — và bản demo của nó nằm phía trên cặp này.

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

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

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

Không biết giới tính? Hãy truyền 'other' một cách tường minh — đó là nhánh trung tính. Nếu vẫn thiếu, SDK sẽ tự dùng nhánh other cho bạn (langsys-js-typescript 0.6.4 trở lên), nên câu vẫn đọc đúng.

Khối nội dung

Vùng <Translate> được đăng ký thành một khối nội dung: phần này được dịch và duyệt như một đơn vị trong Translation Manager, nhưng mỗi đoạn văn bản bên trong vẫn là một cụm từ riêng. Nếu bạn viết lại cùng một câu ở nơi khác, câu đó sẽ dùng lại bản dịch đã có.

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

Danh mục

Các thư viện i18n khác buộc bạn phải tự đặt một khóa cho từng chuỗi vì một từ có thể mang hai nghĩa. Với Langsys, câu văn vẫn nằm trong mã của bạn và danh mục đảm nhiệm vai trò đó: cụm từ cùng danh mục của nó chính là khóa, nên cùng một từ ở hai danh mục sẽ thành hai bản dịch.

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

Thuộc tính

Một biểu mẫu mới chỉ được dịch một nửa nếu văn bản hiển thị thay đổi còn placeholder, phần mô tả hình ảnh và nhãn cho trình đọc màn hình vẫn bằng tiếng Anh. <Translate> xử lý luôn chúng trong cùng một lượt: placeholder, alt, title, aria-label và aria-placeholder được dịch cùng với văn bản, không cần thêm markup nào. Mọi thứ được đánh dấu translate="no" đều bị bỏ qua, kể cả các phần tử con.

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

Số & ngày tháng

Truyền số và ngày tháng dưới dạng tham số, SDK sẽ định dạng chúng theo ngôn ngữ đang hiển thị, tuân theo CLDR (dữ liệu locale của Unicode): số được xử lý qua Intl.NumberFormat và Date qua Intl.DateTimeFormat. Điều này không chỉ bao gồm dấu phân cách: cách nhóm chữ số là một kiểu mẫu, nên 1234567 là 1,234,567 trong tiếng Anh Mỹ và 12,34,567 trong tiếng Anh Ấn Độ (en-IN).

Mặt trái của vấn đề: bất cứ thứ gì được truyền vào dưới dạng số đều bị coi là số lượng. Mã đơn hàng không phải là số lượng, vì vậy hãy truyền nó dưới dạng chuỗi, nếu không tiếng Đức sẽ hiển thị mã đơn hàng của bạn thành 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>

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

Tải danh mục trên máy chủ (SvelteKit) rồi chuyển cho client, để SDK khởi động mà không phải tải lại. SDK dịch trong trình duyệt, nên HTML được dựng phía máy chủ sẽ ở ngôn ngữ gốc cho đến khi SDK khởi động.

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