Translate — content block
Welcome to our store
Browse the catalog in your language.
langsys-js-typescript프레임워크에 구애받지 않는 기본 SDK로, 프레임워크 없이 순수 TypeScript나 JavaScript만으로 사용할 수 있습니다. React, Vue, Svelte 바인딩은 이 패키지를 얇게 감싼 래퍼이며, 여기서는 DOM을 직접 제어합니다. 어디서나 규칙은 같습니다. 코드에 작성한 문구가 조회 키이자 기본 언어의 기본값입니다.
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. npm install langsys-js-typescript 아직 프로젝트나 키가 없으신가요? 빠른 시작으로 2분이면 둘 다 준비할 수 있습니다.
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,
}); 문구와 카테고리를 수정하고 매개변수를 필드 또는 원시 JSON으로 설정한 다음, 로케일을 전환해 실제 SDK가 실시간으로 번역하는 모습을 확인해 보세요.
count를 1로 바꿨다가 다시 되돌려 보세요. 문법이 그에 맞춰 바뀝니다. 문구는 플랫 형태로 작성되어 있습니다. Langsys가 번역 과정에서 (기본 로케일을 포함해) 각 로케일의 복수형을 생성하고, SDK가 count에 따라 분기를 선택합니다. ICU를 직접 입력할 필요가 없습니다. 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 });
}); | 번역 중입니다… | 사용 | 이유 |
|---|---|---|
| 코드 속 일반 문자열로, 라벨, 제목, 메시지 등이 해당됩니다. 매개변수도 포함되며, 수량은 단순하게 작성하면 Langsys가 복수형을 생성합니다. | t() | 문자열을 반환합니다. 코드에 작성한 문구는 조회 키이자 기본 언어의 기본값입니다. |
| 인라인 마크업이나 동적 값이 포함된 한 문장을 나누지 않고 그대로 유지합니다. | Phrase | 인라인 요소는 중립적인 토큰으로 바뀌므로 번역가는 마크업 위치를 포함해 문장 전체의 순서를 바꿀 수 있고, 실제 요소는 렌더링 시점에 다시 복원됩니다. |
| 히어로, 푸터, 카드처럼 여러 문구가 들어 있는 마크업 영역. | Translate | 태그 하나로 해당 영역을 단일 콘텐츠 블록으로 등록합니다. 모든 텍스트 구간이 각각 하나의 문구로 추출되며 마크업 구조는 그대로 유지됩니다. |
| 절대 번역되면 안 되는 내용 — 브랜드명, 코드, ID. | translate="no" | 토크나이저와 렌더러는 해당 하위 트리를 건너뛰므로, 주변 문장이 번역되는 동안에도 그 부분은 원문 그대로 유지됩니다. |
간단한 기준: 문자열 → t() · 마크업이 포함된 문장 → Phrase · 마크업 영역 → Translate · 건드리면 안 되는 부분 → translate="no".
왼쪽에서는 각 바닐라 DOM 핸들러가 실시간으로 실행되고, 오른쪽에서는 이를 연결하는 코드가 표시됩니다.
시청하기 이 기본 요소들의 데모 영상은 현재 Svelte 페이지에 있습니다. 사용 방식은 동일하고 구문만 다릅니다. <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).
Translate — content block
Browse the catalog in your language.
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' }); Phrase — params & markup
Hi {name}, you have {count} items in your cart.
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 },
}); translate="no" — never translated
Welcome! This sentence always stays in English. Thanks for visiting!
// 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' }); 스페인어, 프랑스어, 러시아어는 {username} has been invited을(를) 대상 인물에 맞춰 활용합니다. Langsys는 복수형을 생성하는 것과 같은 방식으로 번역 중에 이러한 분기를 생성하며, 인수 이름은 변수 이름 뒤에 _gender를 붙인 형태이고 값은 male, female, other 중 하나입니다. 알고 있다면 항상 전달하세요. 작동 방식과 이 값이 필요한 문구를 찾는 방법 →
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'
}); 성별을 모르시나요? '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',
});