React langsys-js-react

Un sottile binding React basato su hook sopra langsys-js-typescript. La frase nel tuo codice è sia la chiave di ricerca sia il valore predefinito nella lingua di base: nessun file di chiavi, nessuna fase di estrazione.

Add Langsys translation to this React app.

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

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

Inizializza

import { LangsysApp, createLocaleStore } from 'langsys-js-react';

const locale = createLocaleStore('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,
});

Lettura dei segnali

Hai bisogno di leggere lo store della lingua — o qualsiasi segnale dell'SDK di base, come uno store condiviso fuori da React — in modo reattivo? useSignal(store) si sottoscrive e rieffettua il render del tuo componente a ogni modifica. (Svelte non ha bisogno di un equivalente: i segnali soddisfano nativamente il suo contratto degli store.)

import { useSignal, useCurrentLocale } from 'langsys-js-react';

// React re-renders only on React state — it can't watch a base-SDK
// signal by itself. useSignal(signal) subscribes and re-renders on change.
function LocaleBadge() {
  const selected = useSignal(locale);   // your createLocaleStore(...)
  const loaded = useCurrentLocale();    // shortcut for the loaded locale

  return <footer>selected {selected} · loaded {loaded}</footer>;
}

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 t = useT();
t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3})

import { useT } from 'langsys-js-react';

function Greeting({ name }) {
  const t = useT();
  return <p>{t('Hello, {name}!', 'Greetings', { name })}</p>;
}

Quale devo usare?

Regola pratica: stringa → useT() · frase con markup → <Phrase> · area di markup → <Translate> · intoccabile → <DontTranslate>.

Ogni componente di contenuto visualizzato dal vivo a sinistra; il codice che lo produce 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-react';

<Translate category="Home">
  <h3>Welcome to our store</h3>
  <p>Browse the catalog in your language.</p>
</Translate>

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

<Phrase category="Cart" params={{ name: 'Sarah', count: 3 }}>
  Hi %name%, you have %count% items in your cart.
</Phrase>

import { DontTranslate, Translate } from 'langsys-js-react';

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

import { useT } from 'langsys-js-react';

function LikeNotice({ user }) {
  const t = useT();
  // Pass the agreement argument alongside the value it inflects.
  return <p>{t('{username} has been invited', 'Team', {
    username: user.name,
    username_gender: user.gender, // 'male' | 'female' | 'other'
  })}</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 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',
});