Svelte langsys-js-svelte

Een dunne Svelte 5-binding bovenop langsys-js-typescript — de volwassen, canonieke binding. De basissignalen voldoen al aan het store-contract van Svelte, dus vertalingen lees je met de $-storesyntaxis.

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.

Installeren

npm install langsys-js-svelte

Nog geen project of sleutels? Met de Snelstart heb je beide in twee minuten.

Initialiseren

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

Interactieve playground

Bewerk de zin en categorie, stel de parameters in als velden of ruwe JSON, wissel daarna van locale en zie hoe de echte SDK live vertaalt.

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>

Welke moet ik gebruiken?

Vuistregel: string → $t · zin met opmaak → <Phrase> · gedeelte met opmaak → <Translate> · onaantastbaar → <DontTranslate>.

Elk contentcomponent live gerenderd links; de code die het produceert rechts, en de demo-cut erboven.

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

Geslachtsovereenkomst

Spaans, Frans of Russisch verbuigen {username} has been invited naar de persoon over wie het gaat. Langsys genereert die varianten tijdens het vertalen — op dezelfde manier als meervoudsvormen — en het argument is vernoemd naar de variabele, met _gender erachter: male, female of other. Geef het mee wanneer je het weet. Hoe het werkt en hoe je de zinnen vindt die het nodig hebben →

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

Weet je het geslacht niet? Geef dan expliciet 'other' mee — dat is de neutrale variant. Ontbreekt die toch, dan kiest de SDK voor jou de other-variant (langsys-js-typescript 0.6.4 en hoger), zodat de zin nog steeds goed leest.

Contentblokken

Een <Translate>-regio wordt geregistreerd als één contentblok: de sectie wordt in de Translation Manager als eenheid vertaald en beoordeeld, maar elke tekstfragment erin blijft een eigen zin. Schrijf dezelfde zin ergens anders en de bestaande vertaling wordt hergebruikt.

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

Categorieën

Andere i18n-bibliotheken dwingen je om voor elke string een sleutel te verzinnen, omdat één woord twee dingen kan betekenen. In Langsys blijft de zin in je code staan en doet de categorie dat werk: de frase plus de categorie vormt de sleutel, dus hetzelfde woord in twee categorieën levert twee vertalingen op.

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

Attributen

Een formulier is maar half vertaald als de zichtbare tekst wel verandert, maar de placeholder, de afbeeldingsbeschrijving en het label voor schermlezers in het Engels blijven. <Translate> bereikt ze in dezelfde stap: placeholder, alt, title, aria-label en aria-placeholder worden samen met de tekst vertaald, zonder extra markup. Alles wat is gemarkeerd met translate="no" wordt overgeslagen, inclusief onderliggende elementen.

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

Getallen & datums

Geef getallen en datums mee als parameters en de SDK formatteert ze voor de getoonde taalvariant, volgens CLDR (de Unicode-locale-gegevens): een getal gaat door Intl.NumberFormat en een Date door Intl.DateTimeFormat. Dat omvat meer dan het scheidingsteken: groepering is een patroon, dus 1234567 is 1,234,567 in Amerikaans Engels en 12,34,567 in Indiaas Engels (en-IN).

De keerzijde: alles wat als getal wordt doorgegeven, wordt behandeld als hoeveelheid. Een bestelnummer is dat niet, dus geef het door als string, anders toont Duits je bestelreferentie als 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>

Server-side rendering

Haal de catalogus op de server op (SvelteKit) en geef die door aan de client, zodat de SDK start zonder de catalogus opnieuw op te halen. De SDK vertaalt in de browser, dus de server-side gerenderde HTML staat in de basistaal totdat de SDK start.

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