用語集を使うと、ローカライゼーションエンジンで特定の用語を正確にコントロールできます。訳語を厳密に指定することも、翻訳そのものを完全に禁止することも可能です。用語集の用語はモデル自身の判断より優先されるため、エンジンはすべてのリクエストで一貫して適用します。
用語集は組織所有です。用語を格納する名前付きコンテナで、紐づけることでローカライゼーションエンジンに適用されます。1つの用語集を必要なすべてのエンジンで使え、1つのエンジンに複数の用語集を適用することもできます。
仕組み#
| オブジェクト | フィールド |
|---|---|
| 用語集 | 名前、説明、対象のソースロケール。任意の数の用語を保持します。 |
| 用語 | ソースロケール、ターゲットロケール、ソーステキスト、ターゲットテキスト、タイプ、ヒント。 |
エンジンが翻訳リクエストを処理するとき、紐づいているすべての用語集から、意味検索を使って関連する用語を取得します。照合するのは保存済みのソース用語と入力テキストの意味であり、文字列の完全一致ではありません。
| 項目 | 説明 |
|---|---|
| ソースロケール | ソーステキストのロケール、または任意のソースを表す * |
| ターゲットロケール | ターゲットテキストのロケール、または任意のターゲットを表す * |
| ソーステキスト | ソース言語の用語 |
| ターゲットテキスト | 必須の訳語（または、非翻訳対象なら同じ用語） |
| タイプ | custom_translation または non_translatable |
| ヒント | 用語の意味を明確にするための任意のコンテキスト（例: "名詞、製品機能"） |
用語集は組織所有です#
| アクション | 効果 |
|---|---|
| 用語集を作成 | 組織レベルに作成され、紐づけるまでは何にも適用されません |
| エンジンに紐づける | そのエンジンの翻訳では、この用語集内のすべての用語を取得できます |
| 複数のエンジンに紐づける | 同じ用語がすべてのエンジンに適用されます。1回編集すれば、すべてのエンジンに反映されます |
| 1つのエンジンに複数の用語集を紐づける | それらの用語は1つの取得プールに統合されます |
| エンジンから紐づけを外す | エンジンはその用語集を適用しなくなります。用語集とその用語自体は保持されます。 |
| 用語集を削除 | まだ適用中のエンジンがある間は削除できません。先に紐づけを外してください。削除すると、その用語も一緒に削除されます。 |
| エンジンを削除 | 用語集と用語は残ります。これらはエンジンではなく組織に属します。 |
紐づけ順には意味がありません。紐づいている2つの用語集が、同じロケールペアに対して同じソーステキストを定義している場合、どちらが優先されるかは保証されません。1つの用語は1か所で管理してください。
用語集は組織サイドバーの Glossaries で管理します。エンジンの Glossary タブでは、現在適用中の用語を確認でき、用語集の紐づけや解除も行えます。
ソースロケール#
用語集では、対象とするソースロケールを指定します。ソースロケールがそのどれにも含まれない custom_translation は、ダッシュボード、API、適用済みの engine suggestion、provisioning など、どの経路でも書き込み時に拒否されます。この判定には読み取り時と同じ緩やかなロケール一致が使われるため、en を対象にした用語集は en-US の用語を受け入れます。
ソースロケールを空のままにすると、その用語集はすべてのソースロケールを受け入れます。
非翻訳対象は例外です。紐づけるべきソース言語の翻訳が存在しないためです。また、送信するターゲットにかかわらず、ワイルドカードのターゲットロケールに対して1回だけ保存されます。その用語はすべての言語で保護されるため、ロケールごとの複製は重複になります。
用語集の種類#
カスタム翻訳#
用語に対して特定の訳語を強制します。エンジンは常にモデルの訳ではなく、指定した訳語を使います。
| ソーステキスト | ターゲットテキスト | ソースロケール | ターゲットロケール |
|---|---|---|---|
| Deploy | Bereitstellen | en | de |
| 911 | 112 | en | de |
| workspace | espace de travail | en | fr |
カスタム翻訳の使用例:
- 定訳がある製品用語
- 文化的な調整が必要な表現（緊急通報番号、計量単位など）
- モデルが一貫して誤った同義語を選んでしまう用語
非翻訳対象#
その用語が翻訳されないようにします。エンジンはすべてのターゲットロケールで、ソーステキストをそのまま保持します。
| ソーステキスト | ターゲットテキスト | タイプ |
|---|---|---|
| Lingo.dev | Lingo.dev | non_translatable |
| OAuth | OAuth | non_translatable |
| GraphQL | GraphQL | non_translatable |
非翻訳対象の使用例:
- ブランド名や製品名
- 技術プロトコルや標準規格
- ソース言語のまま残すべき固有名詞
意味ベースのマッチング#
用語集の用語は、文字列の完全一致ではなく意味で照合されます。エンジンが翻訳リクエストを受け取ると、入力テキストの埋め込みを生成し、意味的に近いソーステキストを持つ用語を見つけます。
つまり、"Deploy" の用語は "Deploying"、"deployment"、"deploy your application" にもマッチします。変化形ごとに個別のエントリを作る必要はありません。
ヒント項目
複数の意味を持つ用語を区別したい場合は、ヒント欄を使ってください。たとえば、ヒントが "financial institution" の "bank" という用語は、入力テキスト中の "river bank" にはマッチしません。
ワイルドカードロケール#
ソースまたはターゲットのロケールを * に設定すると、その用語はすべてのロケールペアに適用されます。
一般的なパターン:
| ソーステキスト | ソースロケール | ターゲットロケール | ユースケース |
|---|---|---|---|
| Lingo.dev | * | * | どの言語でもブランド名を翻訳しない |
| API | en | * | すべてのターゲットロケールで "API" を翻訳せずに使う |
| Deploy | en | de | この英語の用語には特定のドイツ語訳を使う |
ワイルドカード用語とロケール固有の用語は組み合わされ、互いに上書きはしません。
ロケールのマッチング#
用語集の用語は、ロケールコードの完全一致だけでなく、地域バリアントをまたいでもマッチします。de の用語は de-DE に適用され、de-DE の用語はロケール指定のない de リクエストに適用されます。de-DE と de-AT のような兄弟関係のロケール同士で用語が共有されることはありません。複数が一致した場合は、CLDR のデフォルト地域が優先されます。同じルールはブランドボイス、ルール、モデル設定にも適用されます。カスタム翻訳のスクリプト安全性ルールを含む挙動の詳細は、Locale Resolution を参照してください。
用語集 vs. ルール vs. ブランドボイス#
それぞれ、エンジン設定の中で異なる役割を担います:
| 用語集 | ルール | ブランドボイス | |
|---|---|---|---|
| 制御対象 | 個別の用語 | 言語上の慣例 | 全体のトーンとスタイル |
| 粒度 | 用語単位 | ルール単位 | ロケールごとのテキスト |
| 一致方法 | 意味ベース（意味による） | 一致するすべてのルールを含む | 最も適合度の高い1つのテキスト |
| 優先順位 | 最優先 - モデルの判断を上書き | 中 - モデルを導く | 最低 - コンテキストを設定 |
| 例 | "Deploy" → "Bereitstellen" | "Straße を Str. に省略する" | "くだけた du を使い、技術的なトーンにする" |
この3つはすべて、エンジンが紐づけによって適用する組織所有のコンテナです。用語集は用語を保持し、rulesets はルールを保持し、ブランドボイス はロケールごとに1つのテキストを保持します。
ルールの優先順位
用語集の用語は、エンジンの階層の中で最優先です。用語集の用語がルールと競合した場合は、用語集が優先されます。ルールは用語集を補完するものとして設計し、重複は避けてください。
APIで用語集を使う#
用語集の用語は、localize endpoint を呼び出すと自動で適用されます。エンジンは、適用中の用語集から、ソースとターゲットのロケールペアに意味的に関連する用語を取得し、プロンプトに含めます。追加のパラメータは不要です。
| 呼び出し | 目的 |
|---|---|
POST /glossaries | 組織の用語集を作成する |
GET /organizations/:id/glossaries | 組織の用語集を、用語数とエンジン数付きで一覧表示する |
GET /glossaries/:id/glossary-items | 用語集の用語をソーステキストごとにグループ化して一覧表示する |
POST /glossary-items with glossaryId | 用語集に用語を追加する |
PUT /engines/:id/glossaries | エンジンが適用する用語集のセットを置き換える |
DELETE /engines/:id/glossaries/:glossaryId | 1つの用語集のエンジンへの適用を停止する |
GET /engines/:id/glossary-items | エンジンが現在適用しているすべての用語を一覧表示する |
ownerEngineId を POST /glossary-items に対して使う方法も引き続き利用できます。これはエンジンのデフォルト用語集に書き込みます。基本的には glossaryId をおすすめします。
アクセス#
org:glossary:read と org:glossary:edit で用語集とその中の用語を管理でき、さらに用語集をエンジンに紐づけるには、そのエンジンに対する engine:edit も必要です。用語集単位の権限付与を使えば、組織内のすべての用語集ではなく、特定の1つの用語集に対してだけ閲覧・編集権限を付与できます。詳しくは Roles & Permissions をご覧ください。
MCP経由で用語集を管理する#
Lingo.dev MCP server を使っている場合は、AI コーディングアシスタントから用語集とその用語を直接管理できます。
"Create a glossary called Product terms covering English, and
apply it to the web engine.""Add a term: translate 'workspace' to 'espace de travail'
for English to French.""Mark 'GraphQL' as non-translatable for all locales."