React langsys-js-react

Тонка обгортка React над langsys-js-typescript, побудована на хуках. Фраза у вашому коді є одночасно ключем пошуку та типовим текстом базової мови — без файлу ключів і кроку вилучення.

Add Langsys translation to this React app.

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

Встановити

npm install langsys-js-react

Ще немає проєкту чи ключів? Швидкий старт дасть вам і те, і інше за дві хвилини.

Ініціалізувати

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

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

Читання сигналів

Потрібно читати сховище локалей — або будь-який сигнал базового SDK, як-от сховище, яке ви використовуєте поза React, — реактивно? useSignal(store) підписується та повторно рендерить ваш компонент у разі змін. (Svelte не потребує аналога: сигнали нативно відповідають його контракту сховища.)

import { useSignal, useCurrentLocale } from 'langsys-js-react';

// React re-renders only on React state — it can't watch a base-SDK
// signal by itself. useSignal(signal) subscribes and re-renders on change.
function LocaleBadge() {
  const selected = useSignal(locale);   // your createLocaleStore(...)
  const loaded = useCurrentLocale();    // shortcut for the loaded locale

  return <footer>selected {selected} · loaded {loaded}</footer>;
}

Інтерактивний пісочник

Відредагуйте фразу й категорію, задайте параметри як поля або сирий JSON, потім змініть локаль і спостерігайте, як справжній SDK перекладає наживо.

const t = useT();
t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3})

import { useT } from 'langsys-js-react';

function Greeting({ name }) {
  const t = useT();
  return <p>{t('Hello, {name}!', 'Greetings', { name })}</p>;
}

Який із них мені використовувати?

Практичне правило: рядок → useT() · речення з розміткою → <Phrase> · ділянка розмітки → <Translate> · не чіпати → <DontTranslate>.

Кожен компонент вмісту відображається наживо ліворуч, а код, що його створює, — праворуч.

Дивитися Демонстрації цих примітивів поки що розміщено на сторінці Svelte — інтерфейс однаковий, відрізняється лише синтаксис: <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).

import { Translate } from 'langsys-js-react';

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

import { Phrase } from 'langsys-js-react';

<Phrase category="Cart" params={{ name: 'Sarah', count: 3 }}>
  Hi %name%, you have %count% items in your cart.
</Phrase>

import { DontTranslate, Translate } from 'langsys-js-react';

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

Узгодження за родом

В іспанській, французькій чи російській мовах {username} has been invited змінюється залежно від особи, про яку йдеться. Langsys генерує ці гілки під час перекладу — так само, як і множинні форми — а аргумент називається за змінною з доданим _gender: male, female або other. Передавайте його щоразу, коли знаєте значення. Як це працює і як знайти фрази, яким це потрібно →

import { useT } from 'langsys-js-react';

function LikeNotice({ user }) {
  const t = useT();
  // Pass the agreement argument alongside the value it inflects.
  return <p>{t('{username} has been invited', 'Team', {
    username: user.name,
    username_gender: user.gender, // 'male' | 'female' | 'other'
  })}</p>;
}

Не знаєте рід? Явно передайте 'other' — це нейтральна гілка. Якщо значення все одно відсутнє, SDK сама вибере гілку other (langsys-js-typescript версії 0.6.4 і новіших), тож речення залишиться коректним. Наразі TypeScript відхиляє username_gender у вбудованому об’єкті параметрів (помилка TS2353; виправлення на розгляді). Поки його не випущено, спочатку створіть об’єкт параметрів, а потім передайте змінну.

Серверний рендеринг

Отримайте каталог на сервері й передайте його клієнту, щоб SDK запускався без повторного завантаження. SDK перекладає в браузері, тому HTML, згенерований на сервері, до його запуску відображається базовою мовою.

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