<Translate> — content block
Welcome to our store
Browse the catalog in your language.
langsys-js-react훅 기반으로 만들어진 langsys-js-typescript 위의 얇은 React 바인딩입니다. 코드에 작성한 구문이 곧 조회 키이자 기본 언어의 기본값이므로 키 파일도, 추출 단계도 필요 없습니다.
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 아직 프로젝트나 키가 없으신가요? 빠른 시작으로 2분이면 둘 다 준비할 수 있습니다.
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,
}); 로캘 저장소나 React 밖에서 공유하는 저장소 같은 기본 SDK 시그널을 반응형으로 읽어야 하나요? 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가 실시간으로 번역하는 모습을 확인해 보세요.
count를 1로 바꿨다가 다시 되돌려 보세요. 문법이 그에 맞춰 바뀝니다. 문구는 플랫 형태로 작성되어 있습니다. Langsys가 번역 과정에서 (기본 로케일을 포함해) 각 로케일의 복수형을 생성하고, SDK가 count에 따라 분기를 선택합니다. ICU를 직접 입력할 필요가 없습니다. Hello, Sarah! You have 3 new messages.
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>;
} | 번역 중입니다… | 사용 | 이유 |
|---|---|---|
| 코드 속 일반 문자열로, 라벨, 제목, 메시지 등이 해당됩니다. 매개변수도 포함되며, 수량은 단순하게 작성하면 Langsys가 복수형을 생성합니다. | useT() | 문자열을 반환합니다. 코드에 작성한 문구는 조회 키이자 기본 언어의 기본값입니다. |
| 인라인 마크업이나 동적 값이 포함된 한 문장을 나누지 않고 그대로 유지합니다. | <Phrase> | 인라인 요소는 중립적인 토큰으로 바뀌므로 번역가는 마크업 위치를 포함해 문장 전체의 순서를 바꿀 수 있고, 실제 요소는 렌더링 시점에 다시 복원됩니다. |
| 히어로, 푸터, 카드처럼 여러 문구가 들어 있는 마크업 영역. | <Translate> | 태그 하나로 해당 영역을 단일 콘텐츠 블록으로 등록합니다. 모든 텍스트 구간이 각각 하나의 문구로 추출되며 마크업 구조는 그대로 유지됩니다. |
| 절대 번역되면 안 되는 내용 — 브랜드명, 코드, ID. | <DontTranslate> | 토크나이저와 렌더러는 해당 하위 트리를 건너뛰므로, 주변 문장이 번역되는 동안에도 그 부분은 원문 그대로 유지됩니다. |
간단한 기준: 문자열 → useT() · 마크업이 포함된 문장 → <Phrase> · 마크업 영역 → <Translate> · 건드리면 안 되는 부분 → <DontTranslate>.
왼쪽에는 각 콘텐츠 컴포넌트가 실시간으로 렌더링되고, 오른쪽에는 이를 만드는 코드가 표시됩니다.
시청하기 이 기본 요소들의 데모 영상은 현재 Svelte 페이지에 있습니다. 사용 방식은 동일하고 구문만 다릅니다. <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).
<Translate> — content blockBrowse the catalog in your language.
import { Translate } from 'langsys-js-react';
<Translate category="Home">
<h3>Welcome to our store</h3>
<p>Browse the catalog in your language.</p>
</Translate> <Phrase> — params & markupimport { Phrase } from 'langsys-js-react';
<Phrase category="Cart" params={{ name: 'Sarah', count: 3 }}>
Hi %name%, you have %count% items in your cart.
</Phrase> <DontTranslate> — never translatedWelcome! This sentence always stays in English. Thanks for visiting!
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는 인라인 params 객체에 있는 username_gender를 거부합니다(오류 TS2353, 수정 사항 검토 중). 수정본이 배포되기 전까지는 params 객체를 먼저 만든 다음 해당 변수를 전달하세요.
서버에서 카탈로그를 가져와 클라이언트에 전달하면 SDK가 카탈로그를 다시 가져오지 않고 바로 시작됩니다. 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',
});