TypeScript langsys-js-typescript

El SDK base independiente de frameworks: TypeScript o JavaScript simple, sin necesidad de un framework. Los bindings de React, Vue y Svelte son envoltorios delgados sobre este paquete; aquí controla el DOM directamente. La misma regla en todas partes: la frase en tu código es a la vez la clave de búsqueda y el valor predeterminado en el idioma base.

Add Langsys translation to this TypeScript app.

1. Read https://docs.langsys.dev/llms.txt, then follow
   https://docs.langsys.dev/learn/sdk/typescript/ 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-typescript

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

Inicializar

import { LangsysApp, createSignal } from 'langsys-js-typescript';

const locale = createSignal('en-US');

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.

import { t, tSignal } from 'langsys-js-typescript';

const greeting = document.querySelector('#greeting');
const name = 'Sarah';

// tSignal re-emits a fresh t() whenever the locale or catalog
// changes — subscribe once and the element stays translated.
tSignal.subscribe(() => {
  greeting.textContent = t('Hello, {name}!', 'Greetings', { name });
});

¿Cuál debo usar?

Regla general: cadena → t() · oración con marcado → Phrase · región con marcado → Translate · intocable → translate="no".

Cada controlador de DOM vanilla funcionando en vivo a la izquierda; el código que lo conecta, a la derecha.

Ver Por ahora, las demostraciones de estas primitivas están en la página de Svelte; la superficie es idéntica, solo cambia la sintaxis: <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).

import { Translate } from 'langsys-js-typescript';

// <section id="hero">
//   <h3>Welcome to our store</h3>
//   <p>Browse the catalog in your language.</p>
// </section>
new Translate(document.querySelector('#hero'), { category: 'Home' });

import { Phrase } from 'langsys-js-typescript';

// <p id="cart-note">Hi {name}, you have {count} items in your cart.</p>
new Phrase(document.querySelector('#cart-note'), {
  category: 'Cart',
  params: { name: 'Sarah', count: 3 },
});

// The standard translate="no" attribute — the tokenizer
// and renderer skip the subtree, so it stays verbatim while
// the sentence around it translates.
// <p id="signin">Welcome! <span translate="no">This sentence always stays in English.</span> Thanks for visiting!</p>
new Translate(document.querySelector('#signin'), { category: 'Tour' });

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 →

import { t } from 'langsys-js-typescript';

// Pass the agreement argument alongside the value it inflects.
t('{username} has been invited', 'Team', {
  username: user.name,
  username_gender: user.gender, // 'male' | 'female' | 'other'
});

¿No conoces el género? Pasa 'other' de forma explícita: es la rama neutra. Si de todos modos falta, el SDK toma la rama other por ti (langsys-js-typescript 0.6.4 y posteriores), de modo que la oración se lea correctamente. Actualmente TypeScript rechaza username_gender en un objeto de parámetros en línea (error TS2353; hay una corrección en revisión). Hasta que se publique, crea primero el objeto de parámetros y pasa la variable.

Renderizado del lado del servidor

Obtén el catálogo en el servidor y pásalo al cliente, para que el SDK inicie sin tener que obtenerlo de nuevo. El SDK traduce en el navegador, así que el HTML renderizado en el servidor queda en el idioma base hasta que el SDK inicia.

// The server fetches the catalog; the client init starts from it
// instead of fetching it again, and translates once it runs.
LangsysApp.init({
  projectid, key,
  UserLocaleStore: locale,
  initialTranslations,        // fetched on the server
  initialTranslationsLocale,  // fetched on the server
  ssrTokenStrategy: 'client',
});