Svelte langsys-js-svelte

langsys-js-typescript üzerinde ince bir Svelte 5 bağlayıcısı — olgun, esas bağlayıcı. Temel sinyaller Svelte'in store sözleşmesini zaten karşıladığından çeviriler $-store sözdizimiyle okunur.

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.

Kurulum

npm install langsys-js-svelte

Henüz projeniz veya anahtarlarınız yok mu? Hızlı başlangıç ikisini de iki dakikada sağlar.

Başlat

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

Etkileşimli deneme alanı

İfadeyi ve kategoriyi düzenleyin, parametreleri alan olarak veya ham JSON olarak ayarlayın, ardından dili değiştirin ve gerçek SDK'nın canlı olarak çeviri yapmasını izleyin.

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>

Hangisini kullanmalıyım?

Pratik kural: dize → $t · biçimlendirme içeren cümle → <Phrase> · biçimlendirme içeren bölge → <Translate> · dokunulmaz → <DontTranslate>.

Her içerik bileşeni solda canlı olarak görüntülenir; onu üreten kod sağdadır ve çiftin üstünde demo kurgusu yer alır.

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

Cinsiyet uyumu

İspanyolca, Fransızca veya Rusça {username} has been invited ifadesini, söz konusu kişiye göre çekimler. Langsys bu dalları çeviri sırasında, çoğulları oluşturduğu gibi oluşturur; argümanın adı değişkenin adına _gender eklenerek verilir: male, female veya other. Bildiğiniz her durumda iletin. Nasıl çalışır ve buna ihtiyaç duyan ifadeler nasıl bulunur →

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

Cinsiyeti bilmiyor musunuz? 'other' değerini açıkça verin — bu nötr daldır. Yine de eksikse SDK sizin yerinize other dalını kullanır (langsys-js-typescript 0.6.4 ve sonrası), böylece cümle yine doğru okunur.

İçerik blokları

Bir <Translate> bölgesi tek bir içerik bloğu olarak kaydedilir: bölüm, Çeviri Yöneticisi'nde tek bir birim olarak çevrilir ve gözden geçirilir, ancak içindeki her metin parçası yine kendi başına bir ifadedir. Aynı cümleyi başka bir yere yazarsanız, onun için zaten var olan çeviri yeniden kullanılır.

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

Kategoriler

Diğer i18n kütüphaneleri, bir kelime iki farklı anlama gelebileceği için her metin dizesi adına bir anahtar uydurmanızı ister. Langsys'te cümle kodunuzda kalır ve bu işi kategori görür: ifade ile kategorisi birlikte anahtardır, dolayısıyla iki farklı kategorideki aynı kelime iki ayrı çeviri olur.

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

Öznitelikler

Görünen metin değişip yer tutucu, görsel açıklaması ve ekran okuyucu etiketi İngilizce kalırsa bir form yalnızca yarı yarıya çevrilmiş olur. <Translate> bunlara da aynı geçişte ulaşır: placeholder, alt, title, aria-label ve aria-placeholder metinle birlikte çevrilir; ek bir işaretleme gerekmez. translate="no" ile işaretlenen her şey, alt öğeler dahil, atlanır.

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

Sayılar ve tarihler

Sayıları ve tarihleri parametre olarak geçirin; SDK bunları gösterilen dile göre CLDR'a (Unicode yerel ayar verileri) uygun biçimde biçimlendirir: sayı Intl.NumberFormat üzerinden, Date ise Intl.DateTimeFormat üzerinden geçer. Bu yalnızca ayırıcıdan fazlasını kapsar: gruplama bir düzendir; yani 1234567, ABD İngilizcesinde 1,234,567, Hint İngilizcesinde (en-IN) ise 12,34,567 olur.

Madalyonun öbür yüzü: sayı olarak iletilen her değer bir miktar olarak ele alınır. Sipariş numarası miktar değildir; bu yüzden onu dize olarak iletin, aksi hâlde Almanca sipariş referansınızı 1.048.576 olarak gösterir.

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

Sunucu tarafı oluşturma

Kataloğu sunucuda (SvelteKit) getirip istemciye iletin; böylece SDK, kataloğu yeniden getirmeden başlar. SDK çeviriyi tarayıcıda yapar, bu nedenle sunucuda oluşturulan HTML, SDK başlayana kadar temel dildedir.

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