Vue `langsys-js-vue`

GitHub ↗ StackBlitz で開く ↗

langsys-js-typescriptの上に構築された薄いVue 3バインディングです。ベースのシグナルをshallowRefにブリッジするコンポーザブルで構成されています。コード内のフレーズが、ルックアップキーであると同時に基準言語のデフォルトにもなります。

AI コーディングエージェントを使っていますか?次のプロンプトを渡してください

Add Langsys translation to this Vue app.

1. Read https://docs.langsys.dev/llms.txt, then follow
   https://docs.langsys.dev/learn/sdk/vue/ 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-vue

プロジェクトやキーをまだお持ちでない場合は、クイックスタートで 2 分ほどで両方とも用意できます。

初期化する

import { LangsysApp, createLocaleStore } from 'langsys-js-vue';

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,
});

シグナルの読み取り

ロケールストアや、Vueの外で共有するストアのようなベースSDKのシグナルをリアクティブに読み取りたい場合は、useSignal(store)を使うと、Vueが追跡できるshallowRefにブリッジできます。（Svelteには同等のものは不要です。シグナルがそのストアコントラクトをそのまま満たしているためです。）

<script setup>
import { useSignal, useCurrentLocale } from 'langsys-js-vue';

// Vue tracks only its own refs — a base-SDK signal is invisible to it.
// useSignal(signal) bridges it into a shallowRef Vue can track.
const selected = useSignal(locale);   // your createLocaleStore(...)
const loaded = useCurrentLocale();    // shortcut for the loaded locale
</script>

<template>
  <footer>selected {{ selected }} · loaded {{ loaded }}</footer>
</template>

インタラクティブプレイグラウンド

フレーズとカテゴリを編集し、パラメーターをフィールドまたは生のJSONで設定してから、ロケールを切り替えて、実際のSDKがリアルタイムで翻訳する様子を確認しましょう。

例 count を 1 にして、また戻してみてください。文法もそれに合わせて変わります。このフレーズはフラットな形で書かれています。Langsys が翻訳時に各ロケール(基準ロケールを含む)の複数形を生成し、SDK が count に応じてブランチを選択します。ICU を手で書く必要はありません。

フレーズ(キー+デフォルト) カテゴリ（任意）

パラメーター

Output

Hello, Sarah! You have 3 new messages.

const t = useT();

<p>{{ t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3}) }}</p>

t() — コンポーネント内のインライン文字列ソースを表示 ↗

<script setup>
import { useT } from 'langsys-js-vue';
const t = useT();
const name = 'Sarah';
</script>

<template>
  <p>{{ t('Hello, {name}!', 'Greetings', { name }) }}</p>
</template>

どれを使えばよいですか?

翻訳中…	使用	理由
コード内のプレーンな文字列(ラベル、タイトル、メッセージなど)です。パラメーターも含められます。数は単純な形で記述すれば、Langsys が複数形を生成します。	`useT()`	文字列を返します。コード内のフレーズが、そのまま検索キーであり、基準言語のデフォルトテキストにもなります。
インラインのマークアップや動的な値を含む1つの文を、分割せずそのまま扱います。	`<Phrase>`	インライン要素は中立的なトークンに置き換えられるため、翻訳者はマークアップの位置も含めて文全体を並べ替えることができ、実際の要素はレンダリング時に復元されます。
ヒーロー、フッター、カードなど、複数のフレーズを含むマークアップの領域。	`<Translate>`	1 つのタグでその領域を 1 つのコンテンツブロックとして登録します。各テキストはそれぞれ個別のフレーズとして抽出され、マークアップ構造は保持されます。
絶対に翻訳してはいけないもの — ブランド名、コード、ID。	`<DontTranslate>`	トークナイザーとレンダラーはそのサブツリーをスキップします。周囲の文は翻訳されますが、その部分は原文のまま残ります。

目安：文字列 → useT() · マークアップを含む文 → <Phrase> · マークアップを含む領域 → <Translate> · 翻訳しないもの → <DontTranslate>。

左側に各コンテンツコンポーネントを実際にレンダリングし、右側にそれを生成するコードを表示します。

視聴するこれらのプリミティブのデモカットは、今のところSvelteのページにあります。インターフェースは同一で、構文だけが異なります： <Translate> (1:04) · <Phrase> (1:06) · <DontTranslate> (0:34).

`<Translate>` — content block

Welcome to our store

Browse the catalog in your language.

<Translate> — コンテンツブロックソースを表示 ↗

<script setup>
import { Translate } from 'langsys-js-vue';
</script>

<template>
  <Translate category="Home">
    <h3>Welcome to our store</h3>
    <p>Browse the catalog in your language.</p>
  </Translate>
</template>

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

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

性の一致

スペイン語、フランス語、ロシア語では、対象となる人物に合わせて {username} has been invited が語形変化します。Langsys は、複数形と同じように、翻訳時にこれらの分岐を生成します。引数の名前は変数名に _gender を付けたもので、値は male、female、other のいずれかです。分かる場合は必ず渡してください。仕組みと、対応が必要なフレーズの見つけ方 →

gender 引数を渡す

<script setup>
import { useT } from 'langsys-js-vue';
const props = defineProps({ user: Object });
const t = useT();
</script>

<template>
  <!-- Pass the agreement argument alongside the value it inflects.
       user.gender is 'male' | 'female' | 'other'. -->
  <p>{{ t('{username} has been invited', 'Team',
       { username: props.user.name, username_gender: props.user.gender }) }}</p>
</template>

性別が分からない場合は、'other' を明示的に渡してください。これは中立のブランチです。それでも渡されていない場合は、SDK が代わりに other ブランチを使用するため(langsys-js-typescript 0.6.4 以降)、文は正しく表示されます。現在、TypeScript ではインラインの params オブジェクト内の username_gender が拒否されます(エラー TS2353。修正はレビュー中です)。修正が公開されるまでは、先に params オブジェクトを作成し、その変数を渡してください。

サーバーサイドレンダリング

サーバー(Nuxt)でカタログを取得してクライアントに渡すと、SDK は再取得せずに開始できます。SDK の翻訳はブラウザー上で行われるため、SDK が起動するまで、サーバーでレンダリングされた HTML はベース言語のままです。

// Nuxt: the server plugin 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',
});

Vue langsys-js-vue