Svelte langsys-js-svelte

Eine schlanke Svelte-5-Anbindung auf Basis von langsys-js-typescript – der ausgereiften, kanonischen Anbindung. Die Basis-Signale erfüllen bereits den Store-Vertrag von Svelte, sodass Übersetzungen mit der $-Store-Syntax gelesen werden.

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.

Installieren

npm install langsys-js-svelte

Noch kein Projekt und keine Schlüssel? Mit dem Schnellstart haben Sie beides in zwei Minuten.

Initialisieren

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

Interaktiver Playground

Bearbeiten Sie Phrase und Kategorie, legen Sie die Parameter als Felder oder als rohes JSON fest, wechseln Sie dann die Locale und sehen Sie live zu, wie das echte SDK übersetzt.

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>

Welches soll ich verwenden?

Faustregel: String → $t · Satz mit Markup → <Phrase> · Markup-Bereich → <Translate> · unantastbar → <DontTranslate>.

Jede Inhaltskomponente links live gerendert, der Code, der sie erzeugt, rechts – und der zugehörige Demoschnitt über dem Paar.

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

Genusübereinstimmung

Spanisch, Französisch oder Russisch flektieren {username} has been invited je nach der Person, um die es geht. Langsys generiert diese Varianten bei der Übersetzung – genauso wie Pluralformen – und das Argument trägt den Namen der Variablen mit angehängtem _gender: male, female oder other. Übergeben Sie es immer, wenn Sie es kennen. So funktioniert es und so finden Sie die Phrasen, die es benötigen →

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

Sie kennen das Geschlecht nicht? Übergeben Sie 'other' ausdrücklich – das ist die neutrale Variante. Fehlt sie trotzdem, übernimmt das SDK automatisch die Variante other (langsys-js-typescript ab Version 0.6.4), sodass der Satz weiterhin korrekt klingt.

Inhaltsblöcke

Ein <Translate>-Bereich wird als ein Inhaltsblock registriert: Der Abschnitt wird im Translation Manager als Einheit übersetzt und geprüft, aber jeder Textabschnitt darin bleibt eine eigene Phrase. Wenn Sie denselben Satz an anderer Stelle schreiben, wird die vorhandene Übersetzung wiederverwendet.

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

Kategorien

Andere i18n-Bibliotheken zwingen dich, für jeden String einen Schlüssel zu erfinden, weil ein Wort zwei Bedeutungen haben kann. In Langsys bleibt der Satz in deinem Code, und die Kategorie übernimmt diese Aufgabe: Der Ausdruck plus seine Kategorie ist der Schlüssel, sodass dasselbe Wort in zwei Kategorien zu zwei Übersetzungen wird.

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

Attribute

Ein Formular ist nur halb übersetzt, wenn sich der sichtbare Text ändert, der Platzhalter, die Bildbeschreibung und das Label für Screenreader aber auf Englisch bleiben. <Translate> erfasst sie im selben Durchgang: placeholder, alt, title, aria-label und aria-placeholder werden zusammen mit dem Text übersetzt, ganz ohne zusätzliches Markup. Alles, was mit translate="no" markiert ist, wird übersprungen, einschließlich untergeordneter Elemente.

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

Zahlen & Datumsangaben

Übergeben Sie Zahlen und Datumsangaben als Parameter, und das SDK formatiert sie gemäß CLDR (den Unicode-Locale-Daten) für die jeweils angezeigte Sprache: Eine Zahl läuft über Intl.NumberFormat, ein Date über Intl.DateTimeFormat. Das betrifft mehr als nur das Trennzeichen: Die Gruppierung ist eine Form, daher wird 1234567 im amerikanischen Englisch zu 1,234,567 und im indischen Englisch (en-IN) zu 12,34,567.

Die Kehrseite: Alles, was als Zahl übergeben wird, gilt als Menge. Eine Bestellnummer ist keine Menge. Übergeben Sie sie daher als String, sonst zeigt Deutsch Ihre Bestellreferenz als 1.048.576 an.

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

Serverseitiges Rendering

Rufen Sie den Katalog auf dem Server ab (SvelteKit) und übergeben Sie ihn an den Client, damit das SDK ohne erneuten Abruf startet. Das SDK übersetzt im Browser, daher liegt das serverseitig gerenderte HTML bis zum Start in der Basissprache vor.

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