Vue langsys-js-vue

Un enlace delgado de Vue 3 sobre langsys-js-typescript, construido con composables que conectan las señales base con shallowRefs. 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 Vue app.

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

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

Inicializar

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

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 el almacén de idiomas —o cualquier señal del SDK base, como un almacén que compartes fuera de Vue— de forma reactiva? useSignal(store) lo conecta con un shallowRef que Vue puede rastrear. (Svelte no necesita un equivalente: las señales cumplen de forma nativa su contrato de stores.)

<script setup>
import { useSignal, useCurrentLocale } from 'langsys-js-vue';

// Vue tracks only its own refs — a base-SDK signal is invisible to it.
// useSignal(signal) bridges it into a shallowRef Vue can track.
const selected = useSignal(locale);   // your createLocaleStore(...)
const loaded = useCurrentLocale();    // shortcut for the loaded locale
</script>

<template>
  <footer>selected {{ selected }} · loaded {{ loaded }}</footer>
</template>

Á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();

<p>{{ t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3}) }}</p>

<script setup>
import { useT } from 'langsys-js-vue';
const t = useT();
const name = 'Sarah';
</script>

<template>
  <p>{{ t('Hello, {name}!', 'Greetings', { name }) }}</p>
</template>

¿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).

<script setup>
import { Translate } from 'langsys-js-vue';
</script>

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

<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 setup>
import { useT } from 'langsys-js-vue';
const props = defineProps({ user: Object });
const t = useT();
</script>

<template>
  <!-- Pass the agreement argument alongside the value it inflects.
       user.gender is 'male' | 'female' | 'other'. -->
  <p>{{ t('{username} has been invited', 'Team',
       { username: props.user.name, username_gender: props.user.gender }) }}</p>
</template>

¿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 (Nuxt) y pásalo al cliente, para que el SDK inicie sin volver a solicitarlo. El SDK traduce en el navegador, por lo que el HTML renderizado en el servidor está en el idioma base hasta que el SDK inicia.

// Nuxt: the server plugin 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',
});