Localization

The chat UI can render in any language, with automatic right-to-left layout. English ships built in and is always the fallback: any string you don't translate shows its English default, so partial translations are safe.

See the full list of translation keys for every translatable string and its English default.

Quick start

Choose a language with the locale attribute and point translations-url at a hosted catalog. No JavaScript required:

<saytv-chat
  app-id="your-app-id"
  locale="es"
  translations-url="https://sdk.saytv.net/@saytv/chat-sdk@latest/locales/es.json"
></saytv-chat>

SayTV hosts ready-made catalogs for the languages below, and right-to-left languages (like Arabic) lay out automatically.

Available languages

Catalogs are hosted on the SDK CDN, CORS-enabled and cached, so translations-url can point straight at them:

Language	locale	Catalog URL
English (template)	en	…/locales/en.json
Arabic (RTL)	ar	…/locales/ar.json
Spanish	es	…/locales/es.json
French	fr	…/locales/fr.json

Pin a version for production

@latest always serves the newest catalogs (short cache). For production, pin a version (e.g. @saytv/chat-sdk@2.2.2/locales/es.json) so the catalog matches the SDK you ship (immutable, cached for a year). The current version is in the top navigation and on the Changelog.

Review machine-generated translations

ar, es, and fr are ready to use but machine-translated, have a native speaker review them before production. en.json is the authoritative key set and is always safe as a template.

Supplying your own translations

Want a language we don't host, or to tweak the wording? Supply your own catalog, a flat map of keys to strings, e.g. { "auth.login.title": "…" }. Provide it one of two ways; either way, untranslated keys fall back to English, so you only translate what you need.

From a URL (no JavaScript)

Host a catalog and point translations-url at it:

<saytv-chat locale="fr" translations-url="https://your-cdn.com/fr.json"></saytv-chat>

The file must be a flat, single-locale catalog matching the locale. If the fetch fails, the widget stays on English.

Don't hotlink the docs site

The /locales/*.json links on this site are for downloading and inspection. For runtime use, host your own copy (or use the SDK CDN), not the docs domain.

From an object (programmatic)

Assign the translations property, keyed by locale, handy when you already have the catalog in JS or switch languages dynamically:

const el = document.querySelector('saytv-chat');
el.translations = {
  ar: { 'auth.login.title': 'مرحبا بعودتك', 'nav.chat': 'الدردشة' },
};
el.setAttribute('locale', 'ar'); // set translations first, then the locale

Interpolation: some values contain {placeholder} tokens the widget fills at runtime. Keep them intact in your translation:

el.translations = { fr: { 'time.minutesAgo': 'il y a {count} min' } };

Customizing & adding a language

Adding a language needs no SDK code, just a catalog:

1. Download the English template, en.json, which lists every key.
2. Translate the values, keeping any {placeholder} tokens as-is.
3. Host it and point translations-url at it (or pass it via translations), then set locale.

Keys are the contract

The translation keys are the stable interface. New SDK versions may add keys; until you translate them they fall back to English, so existing languages keep working.

Switching at runtime & RTL

Changing the locale attribute switches the language live, the widget re-renders, no reload:

document.querySelector('saytv-chat').setAttribute('locale', 'fr');

Right-to-left languages (ar, he, fa, ur, …) set the text direction automatically.

Dates & numbers

Dates and numbers format with the browser's native Intl APIs for the active locale, no setup needed. Relative-time words ("Just now", "Yesterday", "5m ago") come from the catalog (time.* keys), so they translate like any other string.

Framework wrappers

React and Vue expose locale, translations, and translationsUrl props.

// React
<SayTVChat
  appId="your-app-id"
  locale="es"
  translationsUrl="https://sdk.saytv.net/@saytv/chat-sdk@latest/locales/es.json"
/>

<!-- Vue -->
<SayTVChat
  app-id="your-app-id"
  locale="es"
  translations-url="https://sdk.saytv.net/@saytv/chat-sdk@latest/locales/es.json"
/>

Both also accept a translations object. See the React and Vue guides.

Programmatic API

For advanced use, the SDK exports its i18n primitives directly:

import { registerTranslations, setLocale, t, locale, direction } from '@saytv/chat-sdk';

registerTranslations('ar', { 'auth.login.title': 'مرحبا بعودتك' });
setLocale('ar');
t('auth.login.title'); // 'مرحبا بعودتك'
t('time.minutesAgo', { count: 5 }); // interpolated
locale.value; // 'ar'  (signal)
direction.value; // 'rtl' (signal)

Export	Description
setLocale(tag)	Switch the active locale (unknown/empty → en).
registerTranslations(tag, catalog)	Register or extend one locale's catalog.
registerAllTranslations(map)	Register several catalogs at once, keyed by locale.
t(key, params?)	Resolve a key for the active locale, interpolating {tokens}.
locale / direction	Signals holding the active tag and 'ltr'/'rtl'.