Svelte langsys-js-svelte

langsys-js-typescript 위에 구축된 얇은 Svelte 5 바인딩으로, 성숙하고 표준이 되는 바인딩입니다. 기본 시그널이 이미 Svelte의 스토어 규약을 충족하므로 $-스토어 구문으로 번역을 읽을 수 있습니다.

시청 · 1:00 Svelte: 단계별 안내
AI 코딩 에이전트를 사용 중이신가요? 이 프롬프트를 전달해 보세요
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,
});

인터랙티브 플레이그라운드

시청 · 1:09 t(phrase, category, params)

문구와 카테고리를 수정하고 매개변수를 필드 또는 원시 JSON으로 설정한 다음, 로케일을 전환해 실제 SDK가 실시간으로 번역하는 모습을 확인해 보세요.

예시
매개변수
Output

Hello, Sarah! You have 3 new messages.

const value = $derived($t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3}));
t() — 컴포넌트 안의 인라인 문자열 소스 보기 ↗
<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>.

왼쪽에는 각 콘텐츠 컴포넌트가 실시간으로 렌더링되고, 오른쪽에는 이를 만드는 코드가 표시됩니다. 그 위에는 해당 데모 컷이 함께 놓여 있습니다.

시청 · 1:04 <Translate>

<Translate> — content block

Welcome to our store

Browse the catalog in your language.

<Translate> — 콘텐츠 블록 소스 보기 ↗
<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>
시청 · 1:06 <Phrase>

<Phrase> — params & markup

Hi %name%, you have %count% items in your cart.
<Phrase> — 매개변수 및 마크업 (%name%) 소스 보기 ↗
<Phrase category="Cart" params={{ name: 'Sarah', count: 3 }}>
  Hi %name%, you have %count% items in your cart.
</Phrase>
시청 · 0:34 <DontTranslate>

<DontTranslate> — never translated

Welcome! This sentence always stays in English. Thanks for visiting!

<DontTranslate> 소스 보기 ↗
<!-- 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>

성 일치

시청 · 0:39 성별 일치

스페인어, 프랑스어, 러시아어는 {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 이상) 문장은 여전히 올바르게 표시됩니다.

콘텐츠 블록

시청 · 0:42 콘텐츠 블록

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

카테고리

시청 · 0:34 카테고리

다른 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 -->

속성

시청 · 1:07 속성

눈에 보이는 텍스트만 바뀌고 플레이스홀더, 이미지 설명, 스크린 리더 레이블이 영어로 남아 있다면 그 폼은 절반만 번역된 것입니다. <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>

숫자 및 날짜

시청 · 0:46 숫자 및 날짜

숫자와 날짜를 매개변수로 전달하면 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',
});
문서 및 학습 센터 검색