React langsys-js-react

Un enlace ligero de React sobre langsys-js-typescript, basado en hooks. La frase en tu código es a la vez la clave de búsqueda y el valor predeterminado en el idioma base: sin archivo de claves ni paso de extracción.

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.

Instalar

npm install langsys-js-react

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

Inicializar

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

Lectura de señales

¿Necesitas leer de forma reactiva el almacén de configuración regional, o cualquier señal del SDK base, como un almacén que compartes fuera de React? useSignal(store) se suscribe y vuelve a renderizar tu componente cuando hay cambios. (Svelte no necesita un equivalente: las señales cumplen de forma nativa su contrato de almacén.)

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

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

¿Cuál debo usar?

Regla general: cadena → useT() · 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.

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

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

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