Svelte langsys-js-svelte

Cienka warstwa integracji Svelte 5 nad langsys-js-typescript — dojrzałą, referencyjną integracją. Sygnały bazowe już spełniają kontrakt store'ów Svelte, więc tłumaczenia odczytuje się składnią 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.

Instalacja

npm install langsys-js-svelte

Nie masz jeszcze projektu ani kluczy? Szybki start zapewni Ci jedno i drugie w dwie minuty.

Zainicjuj

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

Interaktywne środowisko testowe

Edytuj frazę i kategorię, ustaw parametry jako pola lub surowy JSON, a następnie zmień ustawienia regionalne i zobacz, jak prawdziwe SDK tłumaczy na żywo.

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>

Którego mam użyć?

Zasada praktyczna: ciąg znaków → $t · zdanie ze znacznikami → <Phrase> · obszar ze znacznikami → <Translate> · nietykalne → <DontTranslate>.

Każdy komponent treści wyrenderowany na żywo po lewej; kod, który go tworzy, po prawej — a nad nimi ujęcie demonstracyjne.

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

Zgodność rodzaju gramatycznego

W hiszpańskim, francuskim czy rosyjskim {username} has been invited odmienia się w zależności od osoby, której dotyczy. Langsys generuje te warianty podczas tłumaczenia — tak samo jak liczbę mnogą — a argument ma nazwę zmiennej z dopiskiem _gender: male, female lub other. Przekaż go zawsze, gdy go znasz. Jak to działa i jak znaleźć frazy, które tego potrzebują →

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

Nie znasz płci? Przekaż jawnie 'other' — to gałąź neutralna. Jeśli mimo to jej zabraknie, SDK samo wybierze gałąź other (langsys-js-typescript w wersji 0.6.4 i nowszych), dzięki czemu zdanie nadal brzmi poprawnie.

Bloki treści

Region <Translate> rejestruje się jako jeden blok treści: sekcja jest tłumaczona i weryfikowana jako całość w Translation Manager, ale każdy fragment tekstu wewnątrz niej nadal jest odrębną frazą. Jeśli napiszesz to samo zdanie w innym miejscu, wykorzysta ono istniejące już tłumaczenie.

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

Kategorie

Inne biblioteki i18n każą wymyślać klucz dla każdego ciągu znaków, bo jedno słowo może mieć dwa znaczenia. W Langsys zdanie zostaje w Twoim kodzie, a tę pracę wykonuje kategoria: kluczem jest fraza wraz z kategorią, więc to samo słowo w dwóch kategoriach daje dwa tłumaczenia.

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

Atrybuty

Formularz jest przetłumaczony tylko w połowie, jeśli widoczny tekst się zmienia, a tekst zastępczy, opis obrazu i etykieta dla czytnika ekranu pozostają po angielsku. <Translate> obejmuje je w tym samym przebiegu: placeholder, alt, title, aria-label i aria-placeholder są tłumaczone razem z tekstem, bez dodatkowych znaczników. Wszystko, co oznaczono jako translate="no", jest pomijane wraz z elementami podrzędnymi.

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

Liczby i daty

Przekazuj liczby i daty jako parametry, a SDK sformatuje je zgodnie z wyświetlanym językiem, według CLDR (danych regionalnych Unicode): liczba przechodzi przez Intl.NumberFormat, a Date przez Intl.DateTimeFormat. Obejmuje to więcej niż separator: grupowanie to wzorzec, więc 1234567 to 1,234,567 w amerykańskim angielskim i 12,34,567 w indyjskim angielskim (en-IN).

Druga strona medalu: wszystko, co zostanie przekazane jako liczba, jest traktowane jak ilość. Numer zamówienia nią nie jest, więc przekaż go jako ciąg znaków, bo inaczej niemiecki pokaże numer zamówienia jako 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>

Renderowanie po stronie serwera

Pobierz katalog na serwerze (SvelteKit) i przekaż go klientowi, aby SDK uruchamiało się bez ponownego pobierania. SDK tłumaczy w przeglądarce, więc HTML renderowany na serwerze jest w języku bazowym, dopóki SDK się nie uruchomi.

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