Translate — content block
Welcome to our store
Browse the catalog in your language.
TypeScript langsys-js-typescript
フレームワークに依存しない基本 SDK です。プレーンな TypeScript または JavaScript で動作し、フレームワークは不要です。React、Vue、Svelte のバインディングは、このパッケージの薄いラッパーです。ここでは DOM を直接操作します。ルールはどこでも同じで、コード内のフレーズが検索キーであり、同時にベース言語のデフォルトでもあります。
AI コーディングエージェントを使っていますか?次のプロンプトを渡してください
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 を手で書く必要はありません。 パラメーター
Output
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() | 文字列を返します。コード内のフレーズが、そのまま検索キーであり、基準言語のデフォルトテキストにもなります。 |
| インラインのマークアップや動的な値を含む1つの文を、分割せずそのまま扱います。 | Phrase | インライン要素は中立的なトークンに置き換えられるため、翻訳者はマークアップの位置も含めて文全体を並べ替えることができ、実際の要素はレンダリング時に復元されます。 |
| ヒーロー、フッター、カードなど、複数のフレーズを含むマークアップの領域。 | Translate | 1 つのタグでその領域を 1 つのコンテンツブロックとして登録します。各テキストはそれぞれ個別のフレーズとして抽出され、マークアップ構造は保持されます。 |
| 絶対に翻訳してはいけないもの — ブランド名、コード、ID。 | translate="no" | トークナイザーとレンダラーはそのサブツリーをスキップします。周囲の文は翻訳されますが、その部分は原文のまま残ります。 |
目安：文字列 → t() · マークアップを含む文 → Phrase · マークアップを含む領域 → Translate · 翻訳しないもの → translate="no"。
左側では各バニラDOMハンドラーがライブで動作し、右側ではそれを組み込むコードを確認できます。
視聴する これらのプリミティブのデモカットは、今のところSvelteのページにあります。インターフェースは同一で、構文だけが異なります： <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).
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はブラウザ内で翻訳を行うため、サーバーでレンダリングされたHTMLは、SDKが起動するまで基準言語のままです。
// 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',
});