Vue langsys-js-vue

A thin Vue 3 binding over langsys-js-typescript, built on composables that bridge the base signals into shallowRefs. The phrase in your code is both the lookup key and the base-language default.

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.

Install

npm install langsys-js-vue

No project or keys yet? The Quickstart gets you both in two minutes.

Initialize

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

Reading signals

Need the locale store — or any base-SDK signal, like a store you share outside Vue — read reactively? useSignal(store) bridges it into a shallowRef Vue can track. (Svelte needs no equivalent: the signals natively satisfy its store contract.)

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

Interactive playground

Edit the phrase and category, set the params as fields or raw JSON, then switch locale and watch the real SDK translate live.

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>

Which one do I use?

Rule of thumb: string → useT() · sentence with markup → <Phrase> · region of markup → <Translate> · untouchable → <DontTranslate>.

Each content component rendered live on the left; the code that produces it on the right.

Watch The demo cuts for these primitives are on the Svelte page for now — the surface is identical, only the syntax differs: <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>

Gender agreement

Spanish, French, or Russian inflect {username} has been invited for the person it’s about. Langsys generates those branches during translation — the same way it generates plurals — and the argument is named after the variable, with _gender appended: male, female, or other. Pass it whenever you know it. How it works, and how to find the phrases that need it →

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

Don’t know the gender? Pass 'other' explicitly — it’s the neutral branch. If it is missing anyway, the SDK takes the other branch for you (langsys-js-typescript 0.6.4 and later), so the sentence still reads correctly. TypeScript currently rejects username_gender in an inline params object (error TS2353; a fix is in review). Until it ships, build the params object first and pass the variable.

Server-side rendering

Fetch the catalog on the server (Nuxt) and hand it to the client, so the SDK starts without fetching it again. The SDK translates in the browser, so the server-rendered HTML is in the base language until it starts.

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