TypeScript langsys-js-typescript

L'SDK di base indipendente dal framework — TypeScript o JavaScript puro, nessun framework richiesto. I binding per React, Vue e Svelte sono sottili wrapper di questo pacchetto; qui agisce direttamente sul DOM. Stessa regola ovunque: la frase nel tuo codice è sia la chiave di ricerca sia il valore predefinito nella lingua di 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.

Installa

npm install langsys-js-typescript

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

Inizializza

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

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.

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

Quale devo usare?

Regola pratica: stringa → t() · frase con markup → Phrase · area di markup → Translate · intoccabile → translate="no".

Ogni handler DOM vanilla in esecuzione dal vivo a sinistra; il codice che lo collega a destra.

Guarda Per ora le demo di queste primitive si trovano nella pagina di Svelte: l'interfaccia è identica, cambia solo la sintassi: <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' });

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 →

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

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 versioni successive), così la frase resta corretta. Al momento TypeScript rifiuta username_gender in un oggetto di parametri inline (errore TS2353; una correzione è in fase di revisione). Fino al rilascio, crea prima l'oggetto dei parametri e passa la variabile.

Rendering lato server

Recupera il catalogo sul server e passalo al client, così l'SDK si avvia senza doverlo recuperare di nuovo. L'SDK traduce nel browser, quindi l'HTML renderizzato dal server resta nella lingua di base finché l'SDK non si avvia.

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