Svelte langsys-js-svelte

Une fine couche d'intégration Svelte 5 au-dessus de langsys-js-typescript — l'intégration canonique et éprouvée. Les signaux de base respectent déjà le contrat des stores de Svelte, ce qui permet de lire les traductions avec la syntaxe de 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.

Installer

npm install langsys-js-svelte

Pas encore de projet ni de clés ? Le démarrage rapide vous fournit les deux en deux minutes.

Initialiser

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

Bac à sable interactif

Modifiez la phrase et la catégorie, définissez les paramètres sous forme de champs ou en JSON brut, puis changez de langue et regardez le vrai SDK traduire en direct.

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>

Lequel dois-je utiliser ?

Règle générale : chaîne → $t · phrase avec balisage → <Phrase> · zone de balisage → <Translate> · intouchable → <DontTranslate>.

Chaque composant de contenu est affiché en direct à gauche ; le code qui le produit est à droite, et sa vidéo de démonstration se trouve au-dessus du duo.

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

Accord en genre

L'espagnol, le français ou le russe accordent {username} has been invited selon la personne concernée. Langsys génère ces variantes pendant la traduction — comme il génère les pluriels — et l'argument porte le nom de la variable, suivi de _gender : male, female ou other. Transmettez-le dès que vous le connaissez. Comment cela fonctionne, et comment repérer les phrases concernées →

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

Vous ne connaissez pas le genre ? Passez explicitement 'other' — c’est la variante neutre. S’il est tout de même absent, le SDK utilise pour vous la variante other (langsys-js-typescript 0.6.4 et versions ultérieures), si bien que la phrase reste correcte.

Blocs de contenu

Une région <Translate> s'enregistre comme un seul bloc de contenu : la section est traduite et relue comme un tout dans le Translation Manager, mais chaque segment de texte qu'elle contient reste une phrase à part entière. Si vous écrivez la même phrase ailleurs, elle réutilise la traduction existante.

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

Catégories

Les autres bibliothèques i18n vous obligent à inventer une clé pour chaque chaîne, car un même mot peut avoir deux sens. Avec Langsys, la phrase reste dans votre code et c'est la catégorie qui joue ce rôle : la phrase associée à sa catégorie constitue la clé, si bien qu'un même mot placé dans deux catégories donne deux traductions.

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

Attributs

Un formulaire n'est traduit qu'à moitié si le texte visible change alors que le texte indicatif, la description de l'image et le libellé pour lecteur d'écran restent en anglais. <Translate> les traite dans la même passe : placeholder, alt, title, aria-label et aria-placeholder sont traduits avec le texte, sans balisage supplémentaire. Tout ce qui est marqué translate="no" est ignoré, enfants compris.

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

Nombres et dates

Transmettez les nombres et les dates en paramètres et le SDK les formate pour la langue affichée, selon le CLDR (les données de locale Unicode) : un nombre passe par Intl.NumberFormat et une Date par Intl.DateTimeFormat. Cela couvre plus que le séparateur : le regroupement est une forme, de sorte que 1234567 donne 1,234,567 en anglais américain et 12,34,567 en anglais indien (en-IN).

L’envers du décor : tout ce qui est transmis comme nombre est traité comme une quantité. Un numéro de commande n’en est pas une ; transmettez-le donc sous forme de chaîne, sinon l’allemand affichera votre référence de commande sous la forme 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>

Rendu côté serveur

Récupérez le catalogue côté serveur (SvelteKit) et transmettez-le au client, afin que le SDK démarre sans avoir à le récupérer de nouveau. Le SDK traduit dans le navigateur ; le HTML rendu côté serveur est donc dans la langue de base jusqu’à son démarrage.

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