langsys-js-vue 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+## 0.1.0 - Unreleased
+
+Initial release. `langsys-js-vue` is a thin Vue 3 binding over the framework-agnostic [`langsys-js-typescript`](https://github.com/langsys/langsys-js-typescript) package — the Vue sibling of `langsys-js-react` and `langsys-js-svelte`. The base SDK owns the API client, translation lifecycle, token discovery, DOM tokenizer, and SSR-aware token strategies; this package adds only the Vue-native concerns.
+
+### Added
+
+- **`LangsysApp`** — wrapper whose `init` accepts a `Signal<string>` as `UserLocaleStore` and delegates every other method to the base SDK singleton.
+- **Composables** bridging base-SDK signals into `shallowRef`s with effect-scope disposal:
+    - `useT()` — the current translation function, updating on translations/locale change. Signature: `t(phrase, category?, params?)` with compile-time-checked interpolation params.
+    - `useCurrentLocale()` — the loaded locale.
+    - `useTranslations()` — the raw catalog.
+    - `useLocaleStore(initial?)` — all-in-one `{ locale, setLocale, store }` for the user-locale store.
+    - `useSignal(signal)` — low-level Signal → ref bridge.
+- **`createLocaleStore(initial?)`** — user-locale `Signal<string>` factory (the `writable` analog), and **`refToLocaleSource(ref)`** — adapt an existing Vue `Ref<string>` (Pinia, Nuxt `useState`) into the SDK's store contract with a `flush: 'sync'` watcher.
+- **`<Translate>`** — Vue component wrapping the base SDK's vanilla DOM `Translate` class: tokenizes children into a content block, registers it, re-translates on locale change. Props: `category?`, `custom_id?`, `label?`, `tag?` (default `translate`), `params?` (runtime `{name}` interpolation across content-block text, attributes, and select options, re-applied reactively via `setParams()`); `class` falls through. In markup, author placeholders as `%name%` — the base SDK normalizes them to canonical `{name}` at capture, sidestepping the framework `{{ }}`/`{ }` collision.
+- **`<Phrase>`** — wraps the vanilla `Phrase` rich-text handler. Keeps a markup-bearing run as ONE translatable phrase, encoding inline markup as neutral tokens and reconstituting the real elements at render. Props: `category?`, `params?`, `tag?` (default `span`).
+- **`<DontTranslate>`** — marks a region as never-translated (renders `translate="no"` + `data-ls-dont-translate`), preserved verbatim. Props: `tag?` (default `span`).
+- **Re-exports** from the base SDK: raw signals (`t`, `currentlyLoadedLocale`, `sTranslations`), `createSignal`, `canonicalizeLocale`, `LangsysAppAPI`, and the framework-agnostic types.
+- **SSR (Nuxt) support** via `initialTranslations` / `initialTranslationsLocale` seeding — see `README-SSR.md`.
+
+### Notes
+
+- Built against `langsys-js-typescript` `^0.4.1` — includes `TranslateOptions.params` / `Translate.setParams()` (content-block interpolation) and the `%name%` → `{name}` markup normalization, both surfaced through `<Translate params>` / `<Phrase params>` with no Vue-side placeholder handling.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Flexark International Ltda.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-SSR.md

@@ -0,0 +1,211 @@
+# SSR Usage Guide (Nuxt)
+
+This guide shows how to use `langsys-js-vue` with Server-Side Rendering (SSR) to eliminate duplicate API calls and improve performance.
+
+## The problem
+
+In a traditional SSR flow:
+1. The server fetches translations during render.
+2. The client re-fetches the same translations after hydration.
+3. Duplicate API calls, slower initial render, possible flash of untranslated content.
+
+## The solution
+
+Pass pre-fetched translations from server to client using the `initialTranslations` config option. The client SDK uses them as-is and skips the initial fetch. Because `useSignal` seeds its ref synchronously from the signal's current value, the first paint already reflects the seeded translations.
+
+## Nuxt
+
+### Step 1: Fetch translations on the server
+
+Expose a server route that proxies the Langsys API using a **server-only** key (never ship the write key to the browser):
+
+```typescript
+// server/api/langsys.get.ts
+import type { iCategories } from 'langsys-js-vue';
+
+export default defineEventHandler(async (event) => {
+    const config = useRuntimeConfig();
+    const locale = getQuery(event).locale?.toString() ?? 'en';
+
+    const res = await $fetch<{ data: iCategories }>(
+        `https://api.langsys.dev/api/projects/${config.langsysProjectId}/translations`,
+        {
+            query: { locale },
+            headers: { 'x-Authorization': config.langsysApiKey, 'Content-Type': 'application/json' },
+        }
+    );
+
+    return { locale, translations: res.data };
+});
+```
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+    runtimeConfig: {
+        langsysProjectId: '', // NUXT_LANGSYS_PROJECT_ID (server-only)
+        langsysApiKey: '',    // NUXT_LANGSYS_API_KEY (server-only)
+        public: {
+            langsysProjectId: '', // NUXT_PUBLIC_LANGSYS_PROJECT_ID
+            langsysApiKey: '',    // NUXT_PUBLIC_LANGSYS_API_KEY (read-only key!)
+        },
+    },
+});
+```
+
+### Step 2: Load the payload during SSR and initialize on the client
+
+```vue
+<!-- app.vue -->
+<script setup lang="ts">
+import { LangsysApp, refToLocaleSource } from 'langsys-js-vue';
+
+// Runs on the server during SSR; the payload transfers to the client for free.
+const { data } = await useAsyncData('langsys', () => $fetch('/api/langsys', { query: { locale: 'en' } }));
+
+// Nuxt-owned locale state, adapted to the SDK's store contract.
+const locale = useState('locale', () => data.value?.locale ?? 'en');
+
+onMounted(() => {
+    const config = useRuntimeConfig();
+    LangsysApp.init({
+        projectid: config.public.langsysProjectId,
+        key: config.public.langsysApiKey, // read-only key on the client
+        UserLocaleStore: refToLocaleSource(locale),
+        baseLocale: 'en',
+        initialTranslations: data.value?.translations,
+        initialTranslationsLocale: data.value?.locale,
+        ssrTokenStrategy: 'client',
+    });
+});
+</script>
+
+<template>
+    <NuxtPage />
+</template>
+```
+
+### Step 3: Use translations in any component
+
+```vue
+<script setup lang="ts">
+import { useT } from 'langsys-js-vue';
+
+const t = useT();
+</script>
+
+<template>
+    <h1>{{ t('Welcome', 'HomePage') }}</h1>
+    <p>{{ t('Hello, {name}!', 'HomePage', { name: 'Sarah' }) }}</p>
+</template>
+```
+
+### Detecting the visitor's locale on the server
+
+```typescript
+// server/api/langsys.get.ts (variation)
+import { LangsysApp } from 'langsys-js-vue';
+
+const acceptLanguage = getHeader(event, 'accept-language');
+const locale = LangsysApp.detectPreferredLocale(acceptLanguage) || 'en';
+```
+
+## Locale switching
+
+Write to the same locale state the SDK was initialized with; the SDK reacts and fetches the new locale's translations:
+
+```vue
+<script setup lang="ts">
+import { LangsysApp } from 'langsys-js-vue';
+
+const locale = useState<string>('locale');
+
+function changeLocale(next: string) {
+    locale.value = next; // subscribers in the SDK trigger a fetch
+    return LangsysApp.translationsLoadingPromise; // optional: await the in-flight fetch
+}
+</script>
+
+<template>
+    <select :value="locale" @change="changeLocale(($event.target as HTMLSelectElement).value)">
+        <option value="en">English</option>
+        <option value="es">Español</option>
+        <option value="fr">Français</option>
+    </select>
+</template>
+```
+
+> Keep one locale store for the app (created where you call `init`) and share it via `useState`/Pinia, rather than creating fresh stores in unrelated trees.
+
+## Plain Vite SSR (no Nuxt)
+
+The same handoff works with any Vue SSR setup: fetch the catalog in your server entry, serialize `{ locale, translations }` into the page payload, and call `LangsysApp.init` with `initialTranslations` / `initialTranslationsLocale` in your client entry before mounting.
+
+## Benefits
+
+### Performance
+- No duplicate API calls (server + client).
+- Translations ready immediately on hydration.
+- Faster Time to Interactive (TTI).
+- Reduced API usage and costs.
+
+### User experience
+- No flash of untranslated content.
+- Instant translation display.
+- Better SEO with server-rendered translations.
+
+### Developer experience
+- Simple configuration.
+- Full TypeScript support, including compile-time-checked interpolation params on `t()`.
+
+## Configuration options
+
+### SSR token strategy
+
+```typescript
+{ ssrTokenStrategy: 'client' | 'server' | 'auto' }
+```
+
+- `'client'` (default) — queue tokens, send from client after hydration.
+- `'server'` — send tokens immediately from server.
+- `'auto'` — small batches (≤5) from server, larger batches from client.
+
+### Debug mode
+
+```typescript
+{ debug: true, initialTranslations: translations, initialTranslationsLocale: locale }
+```
+
+Look for:
+- `SSR initial translations config:` on init — confirms pre-fetched data is detected.
+- `Using pre-fetched translations for locale` — confirms the initial fetch was skipped.
+- `Locale change detected!` — fires on a subsequent locale switch.
+
+## Important notes
+
+1. **One-time use.** `initialTranslations` is consumed only at init. Locale changes after init go through the normal fetch path.
+2. **Matching locales.** Always provide `initialTranslationsLocale` with `initialTranslations` so the SDK knows what locale the data represents.
+3. **Data format.** The translations payload must match the `iCategories` shape returned by `LangsysAppAPI.getTranslations()`.
+4. **Cache.** The 60-second locale cache still applies. Pre-fetched translations count as cached.
+5. **Token creation.** Use a read-only API key for the client in production — missing tokens won't be sent. Keep the write key on the server (and ideally pre-populate tokens via your local dev environment).
+6. **Client-side init.** `LangsysApp.init` belongs in `onMounted` (client-only) so the server render and the first client render agree; the seeded signals cover the server output.
+
+## Troubleshooting
+
+### Translations not appearing
+- Check that `initialTranslationsLocale` matches the `UserLocaleStore` value at init.
+- Verify the translations payload matches the `iCategories` shape.
+- Enable `debug: true` and look for the messages above.
+
+### Still seeing duplicate API calls
+- Confirm both `initialTranslations` *and* `initialTranslationsLocale` are passed.
+- Confirm init runs before any rendering that calls `t(...)`.
+- Confirm the locale hasn't drifted between server and client.
+
+### Hydration mismatch warnings
+- Make sure the `locale` you seed on the server matches the initial value of the locale state on the client.
+- Keep `LangsysApp.init` inside `onMounted` (client-only) so the server render and the first client render agree.
+
+### TypeScript errors on `t()`
+- Placeholders are compile-time-checked: `t('Hello, {name}!', 'Cat')` *requires* a params object with `name`. Either add the key or remove the placeholder.
+- Allowed param value types: `string | number | Date | boolean`.

package/README.md

@@ -0,0 +1,307 @@
+# Langsys SDK - Vue
+
+Langsys revolutionizes localization for apps with easy to integrate, realtime, continuous translations. Read more about Langsys Translation Manager [at the website](https://Langsys.dev/).
+
+Integrate the Langsys Translation Manager into your Vue 3, Nuxt, or Vite applications using this SDK.
+
+## Requirements
+
+- **Vue 3.4+** (the reactive layer is built on `shallowRef` + effect-scope disposal).
+
+[![GitHub Release](https://img.shields.io/github/release/langsys/langsys-js-vue.svg?style=flat)]()
+[![GitHub last commit](https://img.shields.io/github/last-commit/langsys/langsys-js-vue.svg?style=flat)]()
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/langsys/langsys-js-vue.svg?style=flat)]()
+[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
+[![NPM License](https://img.shields.io/npm/l/all-contributors.svg?style=flat)](https://github.com/langsys/langsys-js-vue/blob/main/LICENSE)
+
+## How it's layered
+
+`langsys-js-vue` is a thin Vue binding over the framework-agnostic [`langsys-js-typescript`](https://github.com/langsys/langsys-js-typescript) package — which owns the API client, translation lifecycle, token discovery, DOM tokenizer, and SSR-aware token strategies. This package adds only the Vue-native concerns:
+
+- A `LangsysApp` whose `init` accepts a `Signal<string>` (made with `createLocaleStore`, or adapted from a ref with `refToLocaleSource`) for the user locale
+- Composables — `useT`, `useCurrentLocale`, `useTranslations`, `useLocaleStore` — that update components when translations or the loaded locale change
+- Components — `<Translate>` (HTML content blocks), `<Phrase>` (markup-bearing phrases for pluralization), `<DontTranslate>` (never-translated regions)
+
+If you need the SDK outside Vue (a Node script, a non-Vue web app), import from `langsys-js-typescript` directly.
+
+## Install
+
+```bash
+npm install langsys-js-vue
+```
+
+`langsys-js-typescript` is installed automatically as a transitive dependency. `vue` is a peer dependency you already have.
+
+## Creating a Langsys project
+
+Visit [Langsys.dev](https://Langsys.dev/) to create your account, then create your project. Take note of your project ID and API key.
+
+### API key permissions
+
+- **Write key** (development): the SDK auto-creates new translation tokens and content blocks as they appear in your app.
+- **Read-only key** (production): the SDK fetches translations only — no token creation, no content-block writes.
+
+The SDK detects the key type automatically and behaves accordingly.
+
+## Initialization
+
+Initialize once, high in your tree. Create the user-locale store with `useLocaleStore` and pass it to `LangsysApp.init`:
+
+```vue
+<!-- src/LangsysGate.vue -->
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { LangsysApp, useLocaleStore } from 'langsys-js-vue';
+
+const { store } = useLocaleStore('en-US');
+const ready = ref(false);
+const error = ref<string | null>(null);
+
+onMounted(() => {
+    LangsysApp.init({
+        projectid: import.meta.env.VITE_LANGSYS_PROJECT_ID,
+        key: import.meta.env.VITE_LANGSYS_API_KEY,
+        UserLocaleStore: store,
+        baseLocale: 'en-US',
+        debug: false,
+        ssrTokenStrategy: 'client',
+    }).then((res) => {
+        if (res.status) ready.value = true;
+        else error.value = res.errors?.join(', ') ?? 'Init failed';
+    });
+});
+</script>
+
+<template>
+    <p v-if="error">Langsys init failed: {{ error }}</p>
+    <p v-else-if="!ready">Loading…</p>
+    <slot v-else />
+</template>
+```
+
+`UserLocaleStore` is a `Signal<string>` — switch it with `setLocale(...)` (from the same `useLocaleStore` call) or `store.set('fr-FR')`, and the SDK reacts. If you'd rather keep the locale store at module scope, `const localeStore = createLocaleStore('en-US')` works too. And if your app already owns the locale in a `ref` (Pinia state, Nuxt's `useState`), adapt it with `refToLocaleSource(localeRef)` instead.
+
+Locale identifiers are canonicalized to BCP 47 by the base SDK (v0.3.0+): lowercase input like `'en-us'` still works, but `useCurrentLocale()` and `detectPreferredLocale()` always return the canonical form (`'en-US'`) — compare against that, or normalize your own values with the re-exported `canonicalizeLocale()`.
+
+### SSR token strategy
+
+`ssrTokenStrategy` (default `'client'`) controls when missing tokens are sent during server rendering:
+
+- `'client'` — tokens collected on the server are flushed from the client after hydration. Best for performance.
+- `'server'` — tokens are sent immediately during SSR. Best for reliability and immediate registration.
+- `'auto'` — small batches (≤5) sent from server, larger queued for client.
+
+## Using translations
+
+### `useT()` — the everyday API
+
+`useT()` returns the current translation function as a reactive ref, updating the component whenever translations or the loaded locale change.
+
+```vue
+<script setup lang="ts">
+import { useT } from 'langsys-js-vue';
+
+const t = useT();
+</script>
+
+<template>
+    <h1>{{ t('Welcome to my app', 'UI') }}</h1>
+    <p>{{ t('Hello, {name}!', 'UI', { name: 'Sarah' }) }}</p>
+</template>
+```
+
+In templates the ref auto-unwraps, so `t(...)` calls the function directly. In script code, call `t.value(...)`.
+
+The translation function signature is **`t(phrase, category?, params?)`**:
+
+```typescript
+t('Save');                                       // no category, no params
+t('Save', 'UI');                                 // categorized
+t('Hello, {name}!', { name: 'X' });              // no category, with params
+t('Hello, {name}!', 'Greetings', { name: 'X' }); // category + params
+```
+
+The **phrase itself is the lookup key** *and* the base-language default — there's no separate keys file to maintain. The first render of a phrase registers it in the Translation Manager (when using a write key); from then on, translations are fetched and rendered automatically as locales change.
+
+#### Interpolation
+
+Curly-brace placeholders are substituted from the params argument:
+
+```typescript
+t('You have {count} new messages', 'Notifications', { count: 3 });
+```
+
+Placeholder names are extracted from the phrase at compile time and **type-checked**: omitting a required key or adding an extra one is a TypeScript error.
+
+```typescript
+t('You have {count} new messages', 'Notifications', {});
+// ❌ Property 'count' is missing in type '{}'
+
+t('You have {count} new messages', 'Notifications', { count: 3, extra: 'x' });
+// ❌ Object literal may only specify known properties, and 'extra' does not exist
+```
+
+Allowed value types: `string | number | Date | boolean`. Since base SDK 0.3.0, values are locale-formatted: numbers go through `Intl.NumberFormat` (`1234.5` → `1.234,5` in `de-DE`) and `Date` values through `Intl.DateTimeFormat` with the medium date style. Pass a string to opt out of formatting. Formatting always uses the catalog locale (falling back to `en`), never the host's default locale, so server and client render identically.
+
+> Future versions will swap the simple `{name}` runtime for full ICU MessageFormat — adding plural / select — without changing the public signature. Style-less ICU arguments (`{n, number}`, `{d, date}`, `{t, time}`) already format as of base SDK 0.3.0. Today's `t('{count} items', 'Cart', { count })` will evolve to `t('{count, plural, one {# item} other {# items}}', 'Cart', { count })`.
+
+#### Categorization disambiguates context
+
+Different categories give the *same* phrase different translations:
+
+```vue
+<strong>{{ t('Home', 'Main Menu') }}</strong>     <!-- "Inicio" in Spanish -->
+<strong>{{ t('Home', 'Home repairs') }}</strong>  <!-- "Hogar" in Spanish -->
+```
+
+Without categorization, "Home" would only have one translation — which can't work for both contexts. Langsys's philosophy is *translate once, use everywhere*; categorize when the same phrase legitimately means different things.
+
+A good rule for category names: the module or feature the phrase lives in (`Account`, `Errors`, `Checkout`, `UI`).
+
+### `<Translate>` — HTML content blocks
+
+For larger blocks of HTML where the structure should be preserved for the translator:
+
+```vue
+<script setup lang="ts">
+import { Translate } from 'langsys-js-vue';
+</script>
+
+<template>
+    <Translate category="Blog" tag="article">
+        <h1 class="title">My article title</h1>
+        <p>My content <strong>is the best</strong> when internationalized by Langsys.</p>
+        <p>Translators see this exactly as users do — same styling, same structure.</p>
+    </Translate>
+</template>
+```
+
+The component:
+- Recursively tokenizes text nodes and translatable attributes (`placeholder`, `alt`, `title`, `aria-label`, plus button/input `value` attributes and `<option>` text).
+- Captures semantic CSS so translators see the styled appearance in the Translation Manager.
+- Registers the whole thing as a **content block** that translators handle as one unit while still translating the individual phrases inside.
+- Auto re-translates on locale change.
+
+`<Translate>` mounts the SDK's DOM walker on its host element and lets it mutate the rendered output in place, so **keep its children static** — prose, marketing copy, CMS-rendered articles, forms with placeholders. For dynamic per-string values that Vue owns, use `useT()`.
+
+```vue
+<!-- CMS content goes through Translate as-is -->
+<Translate category="News" tag="div">
+    <div v-html="article?.content ?? ''" />
+</Translate>
+```
+
+#### Runtime values with `params` — write placeholders as `%name%`
+
+`<Translate>` accepts a `params` prop for runtime interpolation across its content — text nodes, translatable attributes, and `<select>` options. In markup, **write placeholders with percent delimiters (`%name%`), not `{name}`**:
+
+```vue
+<Translate category="Dashboard" tag="section" :params="{ name: user.name, count: unread }">
+    <p>Welcome back, %name%. You have %count% new messages.</p>
+</Translate>
+```
+
+Why `%name%`: the base SDK normalizes `%name%` back to canonical `{name}` at capture time, so **translators still only ever see `{name}`** and both spellings register the same content block. A single `{name}` actually works in Vue markup (Vue only consumes `{{ }}`, not single braces) — but `%name%` is the portable form the React/Svelte bindings require too, and it avoids the `{{ }}` collision entirely. Only identifiers between the percents match (`%[A-Za-z_][A-Za-z0-9_]*%`), so literal `%` in prose ("50% off", "width: 100%") is left untouched. To keep a *literal* `%WORD%` (e.g. a Windows env var like `%PATH%` in docs text), wrap it in `<DontTranslate>`. The `params` prop is reactive — a changed `count` re-renders via the base SDK's `setParams()`. Placeholders inside `$t()` stay single-brace `{name}` (they live in a JS string, no collision).
+
+`<Translate>` props: `category?`, `custom_id?`, `label?`, `tag?` (defaults to `translate`), `params?`. `class` and other attributes fall through to the host element.
+
+### `<Phrase>` — markup-bearing phrases (pluralization)
+
+Keeps a run that contains inline markup as **one** translatable phrase — so a count variable stays next to the noun it pluralizes, and the translator sees the whole sentence:
+
+```vue
+<script setup lang="ts">
+import { Phrase } from 'langsys-js-vue';
+</script>
+
+<template>
+    <Phrase category="ProductCard" :params="{ n: reviewCount }">
+        Based on {n} <strong>reviews</strong>
+    </Phrase>
+</template>
+```
+
+The inline elements never reach the translator — they're replaced with neutral markup tokens (`{m0o}`…`{m0c}`) and the real framework-owned elements are reconstituted around the translated text at render. This is also what lets reordering languages move emphasis correctly (`<span>White</span> House` → `Casa <span>Blanca</span>`). Pass interpolation values via `params`; keep the markup children static.
+
+> Write the placeholder as `%n%` (the base SDK normalizes it to `{n}` at capture). A single `{n}` also passes through in Vue templates since Vue only consumes `{{ }}` — but `%n%` is the portable form shared with the React/Svelte bindings.
+
+`<Phrase>` props: `category?`, `params?`, `tag?` (defaults to `span`). `class` falls through to the host.
+
+### `<DontTranslate>` — never-translated regions
+
+Marks content that must be preserved verbatim (brand names, domains, code):
+
+```vue
+Built with <DontTranslate>Kangen®</DontTranslate> on <DontTranslate>langsys.dev</DontTranslate>
+```
+
+Renders the host with `translate="no"`, which the base SDK's tokenizer and renderer already honor — the content is never tokenized, registered, or replaced.
+
+`<DontTranslate>` props: `tag?` (defaults to `span`). `class` falls through to the host.
+
+## Composables & reactive primitives
+
+| Export | Type | Notes |
+|---|---|---|
+| `useT()` | `() => Readonly<ShallowRef<TFunction>>` | Updates on translations/locale change. Template: `{{ t('Phrase', 'Cat', params?) }}`; script: `t.value(...)`. |
+| `useCurrentLocale()` | `() => Readonly<ShallowRef<string>>` | The locale whose translations are currently loaded (lags the user-selected locale until the fetch completes). |
+| `useTranslations()` | `() => Readonly<ShallowRef<iCategories>>` | Raw translation catalog. Rarely needed in app code. |
+| `useLocaleStore(initial?)` | `() => { locale, setLocale, store }` | Creates a user-locale `Signal<string>`, reads it reactively, returns a setter. Pass `store` to `init`. |
+| `useSignal(signal)` | `<T>(s: Signal<T>) => Readonly<ShallowRef<T>>` | Low-level: subscribe the current scope to any base-SDK signal. |
+| `createLocaleStore(initial?)` | `(s?: string) => Signal<string>` | Make a user-locale store outside components (module scope). |
+| `refToLocaleSource(ref)` | `(r: Ref<string>) => Signal<string>` | Adapt an existing Vue ref (Pinia, `useState`) into the SDK's locale-store contract. |
+| `t` / `currentlyLoadedLocale` / `sTranslations` | `Signal<…>` | Raw signals for direct subscription outside Vue. In components, prefer the composables. |
+| `canonicalizeLocale(locale)` | `(s: string) => string` | Normalize a locale identifier to canonical BCP 47 (`'en-us'` → `'en-US'`) — the same normalization the SDK applies internally. |
+
+## Server-Side Rendering (Nuxt)
+
+The SDK is SSR-compatible. The main pattern is to pre-fetch translations server-side and seed them through `initialTranslations` / `initialTranslationsLocale` so the client doesn't refetch on hydration. `useSignal` seeds its ref synchronously from the signal's current value, so components hydrate without a flash of untranslated content when seeded.
+
+📖 **See [README-SSR.md](./README-SSR.md)** for a complete Nuxt walkthrough.
+
+## Utilities
+
+`LangsysApp` exposes localized helpers (call them from lifecycle hooks / event handlers):
+
+```typescript
+import { LangsysApp, type iCountryList, type iCurrencyList, type iLocaleDefault } from 'langsys-js-vue';
+
+const countries: iCountryList   = await LangsysApp.getCountries();     // [{ code: "US", label: "United States" }, ...]
+const dialCodes                 = await LangsysApp.getDialCodes();     // [{ country_code: "US", dial_code: "+1", name: "United States" }, ...]
+const currencies: iCurrencyList = await LangsysApp.getCurrencies();    // [{ code: "USD", name: "US Dollar", symbol: "$", ... }, ...]
+const locales: iLocaleDefault   = await LangsysApp.getLocales();       // { "English": [{ code: "en-US", name: "English (US)" }, ...], ... }
+const localeName                = await LangsysApp.getLocaleNameWithLookup('es-ES', true, 'fr-FR'); // "espagnol"
+```
+
+### Detecting the user's preferred locale
+
+```typescript
+// Browser: navigator.languages → fallback to navigator.language
+const locale = LangsysApp.detectPreferredLocale();
+// Returns 'en-US', 'fr', etc., or false if not detected
+
+// SSR (server route / middleware): parses Accept-Language
+const locale = LangsysApp.detectPreferredLocale(event.node.req.headers['accept-language']);
+
+// Matched against your app's supported locales
+const supportedLocales = (await LangsysApp.getLocalesFlat()).map((l) => l.code);
+const locale = LangsysApp.detectPreferredLocale(acceptLanguage, supportedLocales);
+```
+
+The matcher tries exact match first (e.g. `en-US`), then language-only (`en` matches `en-GB`), and is script-aware via CLDR likely-subtags (base SDK 0.3.0+): `zh-TW` matches `zh-Hant` and never falls back to `zh-Hans`. Results are always canonical BCP 47; it returns `false` if no match.
+
+### Waiting for translations to load
+
+When changing locale mid-session, you may want to re-run dependent code after the new translations arrive:
+
+```typescript
+watch(locale, () => {
+    LangsysApp.translationsLoadingPromise.then(() => {
+        // re-render content / regenerate UI here
+    });
+});
+```
+
+## License
+
+MIT © Langsys