<Translate> — content block
Welcome to our store
Browse the catalog in your language.
langsys-js-sveltelangsys-js-typescript 위에 구축된 얇은 Svelte 5 바인딩으로, 성숙하고 표준이 되는 바인딩입니다. 기본 시그널이 이미 Svelte의 스토어 규약을 충족하므로 $-스토어 구문으로 번역을 읽을 수 있습니다.
Add Langsys translation to this Svelte app.
1. Read https://docs.langsys.dev/llms.txt, then follow
https://docs.langsys.dev/learn/sdk/svelte/ 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-svelte 아직 프로젝트나 키가 없으신가요? 빠른 시작으로 2분이면 둘 다 준비할 수 있습니다.
import { writable } from 'svelte/store';
import { LangsysApp } from 'langsys-js-svelte';
const locale = writable('en-US'); // a standard Svelte writable
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를 직접 입력할 필요가 없습니다. Hello, Sarah! You have 3 new messages.
const value = $derived($t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3}));<script>
import { t } from 'langsys-js-svelte';
let name = 'Sarah';
</script>
<p>{$t('Hello, {name}!', 'Greetings', { name })}</p> | 번역 중입니다… | 사용 | 이유 |
|---|---|---|
| 코드 속 일반 문자열로, 라벨, 제목, 메시지 등이 해당됩니다. 매개변수도 포함되며, 수량은 단순하게 작성하면 Langsys가 복수형을 생성합니다. | $t | 문자열을 반환합니다. 코드에 작성한 문구는 조회 키이자 기본 언어의 기본값입니다. |
| 인라인 마크업이나 동적 값이 포함된 한 문장을 나누지 않고 그대로 유지합니다. | <Phrase> | 인라인 요소는 중립적인 토큰으로 바뀌므로 번역가는 마크업 위치를 포함해 문장 전체의 순서를 바꿀 수 있고, 실제 요소는 렌더링 시점에 다시 복원됩니다. |
| 히어로, 푸터, 카드처럼 여러 문구가 들어 있는 마크업 영역. | <Translate> | 태그 하나로 해당 영역을 단일 콘텐츠 블록으로 등록합니다. 모든 텍스트 구간이 각각 하나의 문구로 추출되며 마크업 구조는 그대로 유지됩니다. |
| 절대 번역되면 안 되는 내용 — 브랜드명, 코드, ID. | <DontTranslate> | 토크나이저와 렌더러는 해당 하위 트리를 건너뛰므로, 주변 문장이 번역되는 동안에도 그 부분은 원문 그대로 유지됩니다. |
간단한 기준: 문자열 → $t · 마크업이 포함된 문장 → <Phrase> · 마크업 영역 → <Translate> · 건드리면 안 되는 부분 → <DontTranslate>.
왼쪽에는 각 콘텐츠 컴포넌트가 실시간으로 렌더링되고, 오른쪽에는 이를 만드는 코드가 표시됩니다. 그 위에는 해당 데모 컷이 함께 놓여 있습니다.
<Translate> — content blockBrowse the catalog in your language.
<script>
import { Translate } from 'langsys-js-svelte';
</script>
<Translate category="Home">
<h3>Welcome to our store</h3>
<p>Browse the catalog in your language.</p>
</Translate> <Phrase> — params & markup<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!
<!-- 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 중 하나입니다. 알고 있다면 항상 전달하세요. 작동 방식과 이 값이 필요한 문구를 찾는 방법 →
<script>
import { t } from 'langsys-js-svelte';
export let user; // user.gender is 'male' | 'female' | 'other'
</script>
<!-- Pass the agreement argument alongside the value it inflects. -->
<p>{$t('{username} has been invited', 'Team',
{ username: user.name, username_gender: user.gender })}</p> 성별을 모르시나요? 'other'를 명시적으로 전달하세요. 중립 분기입니다. 그래도 값이 누락되면 SDK가 자동으로 other 분기를 사용하므로(langsys-js-typescript 0.6.4 이상) 문장은 여전히 올바르게 표시됩니다.
<Translate> 영역은 하나의 콘텐츠 블록으로 등록됩니다. 해당 섹션은 Translation Manager에서 하나의 단위로 번역되고 검토되지만, 그 안의 각 텍스트 조각은 여전히 개별 문구입니다. 같은 문장을 다른 곳에 작성하면 이미 있는 번역이 그대로 재사용됩니다.
<Translate category="Home">
<h3>Welcome to our store</h3>
<p>Browse the catalog in your language.</p>
<p>Free shipping on orders over $50.</p>
</Translate> 다른 i18n 라이브러리는 한 단어가 여러 의미를 가질 수 있다는 이유로 모든 문자열마다 키를 새로 만들게 합니다. Langsys에서는 문장이 코드에 그대로 남고 카테고리가 그 역할을 대신합니다. 문구와 카테고리의 조합이 곧 키이므로, 같은 단어라도 두 카테고리에 있으면 두 개의 번역이 됩니다.
<!-- The phrase plus its category is the key. -->
<a href="/">{$t('Home', 'Main menu')}</a> <!-- es: Inicio -->
<h2>{$t('Home', 'Home repairs')}</h2> <!-- es: Hogar --> 눈에 보이는 텍스트만 바뀌고 플레이스홀더, 이미지 설명, 스크린 리더 레이블이 영어로 남아 있다면 그 폼은 절반만 번역된 것입니다. <Translate>는 같은 과정에서 이들까지 처리합니다. placeholder, alt, title, aria-label, aria-placeholder가 텍스트와 함께 번역되며, 별도의 마크업은 필요하지 않습니다. translate="no"로 표시된 항목은 자식 요소를 포함해 건너뜁니다.
<Translate category="Checkout">
<label>Email address</label>
<input placeholder="[email protected]" />
<img src="/lock.svg" alt="Secure checkout" />
<button aria-label="Place your order">
Place order
</button>
</Translate> 숫자와 날짜를 매개변수로 전달하면 SDK가 CLDR(유니코드 로케일 데이터)에 따라 표시되는 로케일에 맞게 형식을 지정합니다. 숫자는 Intl.NumberFormat을, Date는 Intl.DateTimeFormat을 거칩니다. 구분 기호뿐만 아니라 더 많은 것을 처리합니다. 자릿수 묶음은 하나의 형태이므로 1234567은 미국 영어에서는 1,234,567, 인도 영어(en-IN)에서는 12,34,567이 됩니다.
반대로, 숫자로 전달된 값은 모두 수량으로 취급됩니다. 주문 번호는 수량이 아니므로 문자열로 전달하세요. 그렇지 않으면 독일어에서 주문 참조 번호가 1.048.576으로 표시됩니다.
<script lang="ts">
import { t } from 'langsys-js-svelte';
const renewsAt = new Date(2026, 2, 14); // 14 March 2026, local time
</script>
<p>{$t('Balance: {amount}', 'Billing', { amount: 1234.5 })}</p>
<p>{$t('Renews {when}', 'Billing', { when: renewsAt })}</p>
<!-- An order number is not a quantity: pass it as a string. -->
<p>{$t('Order {ref}', 'Billing', { ref: '1048576' })}</p> 서버(SvelteKit)에서 카탈로그를 가져와 클라이언트에 전달하면 SDK가 다시 가져오지 않고 바로 시작합니다. SDK는 브라우저에서 번역하므로, SDK가 시작되기 전까지 서버에서 렌더링된 HTML은 기본 언어로 표시됩니다.
// SvelteKit: +layout.server.ts seeds the catalog, the client init reuses it.
LangsysApp.init({
projectid, key,
UserLocaleStore: locale,
initialTranslations, // fetched on the server
initialTranslationsLocale, // fetched on the server
ssrTokenStrategy: 'client',
});