Svelte langsys-js-svelte

Un sottile binding Svelte 5 basato su langsys-js-typescript, il binding canonico e maturo. I segnali di base soddisfano già il contratto degli store di Svelte, quindi le traduzioni si leggono con la sintassi degli 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.

Installa

npm install langsys-js-svelte

Non hai ancora un progetto o le chiavi? La guida rapida ti dà entrambi in due minuti.

Inizializza

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

Playground interattivo

Modifica la frase e la categoria, imposta i parametri come campi o JSON grezzo, poi cambia lingua e guarda l'SDK reale tradurre in tempo reale.

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>

Quale devo usare?

Regola pratica: stringa → $t · frase con markup → <Phrase> · area di markup → <Translate> · intoccabile → <DontTranslate>.

Ogni componente di contenuto è mostrato dal vivo a sinistra, con il codice che lo produce a destra e il relativo montaggio demo sopra la coppia.

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

Concordanza di genere

Spagnolo, francese o russo flettono {username} has been invited in base alla persona a cui ci si riferisce. Langsys genera queste varianti durante la traduzione — nello stesso modo in cui genera i plurali — e l'argomento prende il nome dalla variabile, con _gender aggiunto in coda: male, female oppure other. Passalo ogni volta che lo conosci. Come funziona e come trovare le frasi che ne hanno bisogno →

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

Non conosci il genere? Passa 'other' in modo esplicito: è il ramo neutro. Se manca comunque, l'SDK usa per te il ramo other (langsys-js-typescript 0.6.4 e successive), così la frase si legge comunque correttamente.

Blocchi di contenuto

Una regione <Translate> viene registrata come un unico blocco di contenuto: la sezione viene tradotta e revisionata come un'unità nel Translation Manager, ma ogni porzione di testo al suo interno resta comunque una frase a sé. Se scrivi la stessa frase altrove, riutilizza la traduzione già esistente.

<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

Altre librerie i18n ti costringono a inventare una chiave per ogni stringa, perché una stessa parola può avere due significati. In Langsys la frase resta nel tuo codice e a svolgere questo compito è la categoria: la frase insieme alla sua categoria è la chiave, quindi la stessa parola in due categorie diventa due traduzioni.

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

Attributi

Un modulo è tradotto solo a metà se il testo visibile cambia mentre il segnaposto, la descrizione dell'immagine e l'etichetta per lo screen reader restano in inglese. <Translate> li raggiunge nello stesso passaggio: placeholder, alt, title, aria-label e aria-placeholder vengono tradotti insieme al testo, senza markup aggiuntivo. Tutto ciò che è contrassegnato con translate="no" viene ignorato, figli inclusi.

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

Numeri e date

Passa numeri e date come parametri e l'SDK li formatta per la lingua visualizzata, seguendo CLDR (i dati locali di Unicode): un numero passa da Intl.NumberFormat e una Date da Intl.DateTimeFormat. Non si tratta solo del separatore: il raggruppamento è una struttura, quindi 1234567 diventa 1,234,567 in inglese statunitense e 12,34,567 in inglese indiano (en-IN).

Il rovescio della medaglia: qualsiasi valore passato come numero viene trattato come una quantità. Un numero d'ordine non lo è, quindi passalo come stringa, altrimenti in tedesco il riferimento dell'ordine verrà mostrato come 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>

Rendering lato server

Recupera il catalogo sul server (SvelteKit) e passalo al client, così l'SDK parte senza doverlo recuperare di nuovo. L'SDK traduce nel browser, quindi l'HTML renderizzato dal server resta nella lingua di base fino al suo avvio.

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