Svelte langsys-js-svelte

Тонка обгортка Svelte 5 над langsys-js-typescript — зрілою канонічною обгорткою. Базові сигнали вже відповідають контракту сторів Svelte, тож переклади читаються із синтаксисом стору $.

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.

Встановити

npm install langsys-js-svelte

Ще немає проєкту чи ключів? Швидкий старт дасть вам і те, і інше за дві хвилини.

Ініціалізувати

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

Інтерактивний пісочник

Відредагуйте фразу й категорію, задайте параметри як поля або сирий JSON, потім змініть локаль і спостерігайте, як справжній SDK перекладає наживо.

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 · речення з розміткою → <Phrase> · ділянка розмітки → <Translate> · не чіпати → <DontTranslate>.

Кожен контентний компонент показано наживо ліворуч, а код, що його створює, — праворуч; над парою розміщено його демонарізку.

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

Узгодження за родом

В іспанській, французькій чи російській мовах {username} has been invited змінюється залежно від особи, про яку йдеться. Langsys генерує ці гілки під час перекладу — так само, як і множинні форми — а аргумент називається за змінною з доданим _gender: male, female або other. Передавайте його щоразу, коли знаєте значення. Як це працює і як знайти фрази, яким це потрібно →

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

Не знаєте рід? Явно передайте 'other' — це нейтральна гілка. Якщо його все одно не вказано, SDK сам використає гілку other (починаючи з версії 0.6.4 langsys-js-typescript), тож речення однаково читатиметься правильно.

Блоки вмісту

Область <Translate> реєструється як один контентний блок: розділ перекладається та перевіряється як єдине ціле в Translation Manager, але кожен текстовий фрагмент усередині нього все одно залишається окремою фразою. Якщо написати те саме речення в іншому місці, воно використає переклад, який уже існує.

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

Категорії

Інші бібліотеки i18n змушують вигадувати ключ для кожного рядка, адже те саме слово може мати два значення. У Langsys речення залишається у вашому коді, а цю роль виконує категорія: ключ — це фраза разом із її категорією, тож те саме слово у двох категоріях стає двома різними перекладами.

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

Атрибути

Форма перекладена лише наполовину, якщо видимий текст змінюється, а плейсхолдер, опис зображення та мітка для скрінрідера залишаються англійською. <Translate> охоплює їх за один прохід: placeholder, alt, title, aria-label і aria-placeholder перекладаються разом із текстом, без додаткової розмітки. Усе, що позначено translate="no", пропускається разом із дочірніми елементами.

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

Числа й дати

Передавайте числа й дати як параметри, і SDK відформатує їх для відображуваної локалі за CLDR (дані локалей Unicode): число обробляється через Intl.NumberFormat, а Date — через Intl.DateTimeFormat. Це стосується не лише роздільника: групування — це шаблон, тож 1234567 у американській англійській виглядає як 1,234,567, а в індійській англійській (en-IN) — як 12,34,567.

Зворотний бік: усе, що передається як число, вважається кількістю. Номер замовлення нею не є, тому передавайте його як рядок, інакше німецькою мовою номер вашого замовлення відобразиться як 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>

Серверний рендеринг

Отримайте каталог на сервері (SvelteKit) і передайте його клієнту, щоб SDK стартував без повторного завантаження. SDK перекладає в браузері, тож HTML, відрендерений на сервері, до запуску SDK залишається базовою мовою.

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