TypeScript langsys-js-typescript

De frameworkonafhankelijke basis-SDK — gewone TypeScript of JavaScript, geen framework nodig. De bindings voor React, Vue en Svelte zijn dunne wrappers rond dit pakket; hier stuurt het direct de DOM aan. Overal dezelfde regel: de zin in je code is zowel de opzoeksleutel als de standaardtekst in de basistaal.

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.

Installeren

npm install langsys-js-typescript

Nog geen project of sleutels? Met de Snelstart heb je beide in twee minuten.

Initialiseren

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

Interactieve playground

Bewerk de zin en categorie, stel de parameters in als velden of ruwe JSON, wissel daarna van locale en zie hoe de echte SDK live vertaalt.

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

Welke moet ik gebruiken?

Vuistregel: string → t() · zin met opmaak → Phrase · gedeelte met opmaak → Translate · onaantastbaar → translate="no".

Elke vanilla DOM-handler live aan het werk links; de code die hem aansluit rechts.

Bekijken De democlips voor deze primitieven staan voorlopig op de Svelte-pagina — de interface is identiek, alleen de syntaxis verschilt: <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' });

Geslachtsovereenkomst

Spaans, Frans of Russisch verbuigen {username} has been invited naar de persoon over wie het gaat. Langsys genereert die varianten tijdens het vertalen — op dezelfde manier als meervoudsvormen — en het argument is vernoemd naar de variabele, met _gender erachter: male, female of other. Geef het mee wanneer je het weet. Hoe het werkt en hoe je de zinnen vindt die het nodig hebben →

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

Weet je het geslacht niet? Geef 'other' dan expliciet mee — dat is de neutrale tak. Ontbreekt die toch, dan kiest de SDK voor jou de other-tak (langsys-js-typescript 0.6.4 en later), zodat de zin nog steeds goed leest. TypeScript weigert momenteel username_gender in een inline params-object (fout TS2353; een oplossing wordt beoordeeld). Tot die beschikbaar is, bouw je eerst het params-object en geef je de variabele mee.

Server-side rendering

Haal de catalogus op de server op en geef hem door aan de client, zodat de SDK start zonder hem opnieuw op te halen. De SDK vertaalt in de browser, dus de op de server gerenderde HTML staat in de basistaal totdat de SDK start.

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