Svelte langsys-js-svelte

Un binding ligero de Svelte 5 sobre langsys-js-typescript, el binding canónico y maduro. Las señales base ya cumplen el contrato de stores de Svelte, por lo que las traducciones se leen con la sintaxis 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.

Instalar

npm install langsys-js-svelte

¿Aún no tienes proyecto ni claves? El Inicio rápido te da ambos en dos minutos.

Inicializar

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

Área de pruebas interactiva

Edita la frase y la categoría, define los parámetros como campos o en JSON sin procesar, y luego cambia la configuración regional y observa cómo el SDK real traduce en vivo.

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>

¿Cuál debo usar?

Regla general: cadena → $t · oración con marcado → <Phrase> · región con marcado → <Translate> · intocable → <DontTranslate>.

Cada componente de contenido se muestra en vivo a la izquierda; el código que lo produce, a la derecha, y su corte de demostración encima del par.

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

Concordancia de género

El español, el francés o el ruso flexionan {username} has been invited según la persona a la que se refiere. Langsys genera esas ramas durante la traducción, igual que genera los plurales, y el argumento lleva el nombre de la variable con _gender al final: male, female u other. Pásalo siempre que lo sepas. Cómo funciona y cómo encontrar las frases que lo necesitan →

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

¿No sabes el género? Pasa 'other' de forma explícita: es la variante neutra. Si aun así falta, el SDK usa la variante other por ti (langsys-js-typescript 0.6.4 y posteriores), de modo que la oración se lea correctamente.

Bloques de contenido

Una región <Translate> se registra como un bloque de contenido: la sección se traduce y se revisa como una unidad en el Translation Manager, pero cada fragmento de texto dentro de ella sigue siendo una frase independiente. Si escribes la misma oración en otro lugar, reutiliza la traducción que ya existe.

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

Categorías

Otras bibliotecas de i18n te obligan a inventar una clave para cada cadena porque una misma palabra puede significar dos cosas. En Langsys la oración se queda en tu código y la categoría hace ese trabajo: la frase junto con su categoría es la clave, así que la misma palabra en dos categorías se convierte en dos traducciones.

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

Atributos

Un formulario queda traducido a medias si cambia el texto visible, pero el marcador de posición, la descripción de la imagen y la etiqueta para lectores de pantalla siguen en inglés. <Translate> los alcanza en la misma pasada: placeholder, alt, title, aria-label y aria-placeholder se traducen junto con el texto, sin marcado adicional. Todo lo marcado con translate="no" se omite, incluidos sus elementos hijos.

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

Números y fechas

Pasa números y fechas como parámetros y el SDK los formatea según el idioma que se muestra, siguiendo CLDR (los datos de configuración regional de Unicode): un número pasa por Intl.NumberFormat y un Date por Intl.DateTimeFormat. Eso abarca más que el separador: la agrupación es una forma, así que 1234567 es 1,234,567 en inglés de EE. UU. y 12,34,567 en inglés de la India (en-IN).

La otra cara de la moneda: todo lo que se pasa como número se trata como una cantidad. Un número de pedido no lo es, así que pásalo como cadena de texto, o en alemán se mostrará tu referencia de pedido como 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>

Renderizado del lado del servidor

Obtén el catálogo en el servidor (SvelteKit) y entrégaselo al cliente, para que el SDK inicie sin volver a obtenerlo. El SDK traduce en el navegador, así que el HTML renderizado en el servidor está en el idioma base hasta que el SDK inicia.

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