Contents
カスタム辞書（Glossary）とは
Glossary は Cloud Translation API の拡張機能で、「sourceLanguageCode」「targetLanguageCode」「term」「translation」 の 4 列からなる CSV/TSV ファイルで用語とその固定訳を定義します。
標準のニューラル機械翻訳（NMT）は大量の汎用コーパスで学習されているため、固有名詞やブランド表記が期待通りに変換されないことがあります。Glossary を併用すると、指定した語句だけを辞書通りに上書きしつつ、残りの文章は NMT が自然に生成します。
重要ポイント：Glossary は「上書き的」に働くため、翻訳全体の品質は NMT に委ねられますが、対象語句だけは必ず期待通りの訳になる点が最大のメリットです。
前提条件と環境設定
このセクションでは Glossary を利用開始するまでに必要な Google Cloud の基礎設定を解説します。プロジェクト作成や API 有効化、適切な IAM 権限付与は、後続の手順がエラーなく実行できるかどうかの根幹となります。
1. プロジェクト作成と Translation API の有効化
Google Cloud コンソールで新規プロジェクトを作成し、Cloud Translation API を有効にします。
API が無効な状態では Glossary の作成・参照・翻訳リクエストすべてが 403 エラーとなります。
2. IAM ロールの最小権限構成
Glossary の管理と翻訳リクエストには以下のロールを組み合わせることが推奨されています。最小権限の原則（Principle of Least Privilege） に従い、必要な権限だけを付与してください。
| ロール | 主な権限 | 推奨用途 |
|---|---|---|
roles/cloudtranslate.admin |
Glossary の作成・取得・更新・削除、翻訳リクエスト時の設定変更 | Glossary 全般の管理者 |
roles/cloudtranslate.user |
翻訳リクエスト実行、Glossary 設定の参照 | 翻訳のみを実行するアプリケーションやユーザー |
roles/viewer（任意） |
プロジェクトや課金情報の閲覧 | コスト管理者が必要な場合のみ付与 |
注記：
viewerロールは必須ではなく、コスト確認が必要なメンバーにだけ限定的に付与します。
IAM の設定はプロジェクトレベルでもフォルダレベルでも可能ですが、組織全体で統一したポリシーを適用すると管理負荷が低減します。
Glossary 用ファイルの作成方法
Glossary にアップロードできるファイル形式と必須項目について詳しく説明します。ここで示す要件を満たさないと、作成時にバリデーションエラーが発生します。
1. ファイルフォーマットと必須ヘッダー
CSV（カンマ区切り）または TSV（タブ区切り）のいずれかで、UTF‑8 エンコーディング が必須です。ファイルの最初の行はヘッダーとして下表の列名を使用します。
| 列名 | 説明 |
|---|---|
sourceLanguageCode |
元テキストの言語コード（例: en） |
targetLanguageCode |
翻訳先の言語コード（例: ja） |
term |
辞書に登録したい原文用語 |
translation |
用語の固定訳 |
ポイント：ヘッダーは必ず小文字で記載し、余計な空白や BOM を入れないよう注意してください。
2. サンプル CSV とエスケープ規則
以下は UTF‑8 エンコードされた CSV の例です。カンマや改行を含む語句は必ず二重引用符で囲みます。
|
1 2 3 4 5 |
sourceLanguageCode,targetLanguageCode,term,translation en,ja,Google Cloud,グーグルクラウド en,ja,API,エーピーアイ en,ja,"e.g., example","例：" |
エスケープのポイント
- フィールド内に
"（二重引用符）を含める場合は""と2つ連続させます。 - 改行文字は
\nではなく、CSV の規格どおりフィールド全体を" "で囲むことで表現できます。
Glossary の作成手順
Glossary は Google Cloud Console・gcloud CLI・REST API（もしくは公式クライアント）のいずれかから作成可能です。ここではそれぞれの実装例と注意点を示します。
1. コンソールでの作成手順
コンソール UI は初心者に最適で、ファイルアップロード時に自動バリデーションが走ります。
- 左側メニュー → Translation → 用語集（Glossaries） を選択
- 「作成」ボタンをクリックし、名称・説明を入力
- 「ファイルのアップロード」で先ほど作成した CSV/TSV を指定
- 言語ペア（例：
en‑ja）を確認し、リージョン（ロケーション）を選択して「作成」を確定
ヒント：リージョンは
globalが非推奨となっているため、us-central1など実際にデータが保存される場所を指定してください。
2. gcloud CLI を用いた作成例
CLI はスクリプト化しやすく CI/CD パイプラインにも組み込みやすいです。以下は基本的なコマンドです。
|
1 2 3 4 5 6 |
gcloud translate glossaries create my-glossary \ --project=YOUR_PROJECT_ID \ --location=us-central1 \ --input-uri=gs://my-bucket/glossary.csv \ --language-pair=en:ja |
| オプション | 説明 |
|---|---|
--input-uri |
Cloud Storage 上の CSV/TSV パス（必須） |
--location |
Glossary の保存リージョン。global は使用しないこと |
--language-pair |
source:target 形式で言語ペアを指定 |
エラーハンドリングのポイント
- 404 Not Found：入力ファイルが Cloud Storage に存在しない場合はパスとアクセス権限を確認。
- INVALID_ARGUMENT：CSV のヘッダーやエンコーディングが不正なときに返るので、ローカルで
file -i等で UTF‑8 を再確認。
3. REST API / クライアントライブラリのサンプル
Python（google-cloud-translate v3）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
from google.cloud import translate_v3 as translate client = translate.TranslationServiceClient() parent = f"projects/YOUR_PROJECT_ID/locations/us-central1" glossary = { "name": f"{parent}/glossaries/my-glossary", "language_codes_set": {"language_codes": ["en", "ja"]}, "input_config": { "gcs_source": {"input_uri": "gs://my-bucket/glossary.csv"}, "mime_type": "text/csv" } } operation = client.create_glossary(parent=parent, glossary=glossary) result = operation.result() print(f"Glossary created: {result.name}") |
Node.js（@google-cloud/translate v3）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
const {TranslationServiceClient} = require('@google-cloud/translate').v3; const client = new TranslationServiceClient(); async function createGlossary() { const parent = `projects/YOUR_PROJECT_ID/locations/us-central1`; const glossary = { name: `${parent}/glossaries/my-glossary`, languageCodesSet: {languageCodes: ['en', 'ja']}, inputConfig: { gcsSource: {inputUri: 'gs://my-bucket/glossary.csv'}, mimeType: 'text/csv', }, }; const [operation] = await client.createGlossary({parent, glossary}); const [response] = await operation.promise(); console.log(`Glossary created: ${response.name}`); } createGlossary(); |
REST エンドポイント：
https://translation.googleapis.com/v3/projects/{project-id}/locations/{location}/glossaries
リクエストボディは上記コードと同等の JSON 形式です。
翻訳リクエストに Glossary を組み込む
Glossary が正しく適用されたかを検証するには、翻訳 API の glossaryConfig フィールドに作成した Glossary のフルリソース名を指定します。
1. translateText リクエスト例（JSON）
|
1 2 3 4 5 6 7 8 9 10 11 |
POST https://translation.googleapis.com/v3/projects/YOUR_PROJECT_ID/locations/us-central1:translateText { "contents": ["Google Cloud offers powerful translation services."], "mimeType": "text/plain", "sourceLanguageCode": "en", "targetLanguageCode": "ja", "glossaryConfig": { "glossary": "projects/YOUR_PROJECT_ID/locations/us-central1/glossaries/my-glossary" } } |
2. 結果比較
| 設定 | 翻訳結果 |
|---|---|
| Glossary 未指定 | Google Cloud は強力な翻訳サービスを提供しています。 |
| Glossary 指定 | グーグルクラウドは強力な翻訳サービスを提供しています。 |
上記のように、Google Cloud が辞書通り グーグルクラウド に置き換わっていることが確認できます。
ポイント：Glossary は単語レベルで適用されるため、文全体の自然さは NMT が担います。実運用ではテストケースを自動化し、期待通りに変換されたかを CI で検証すると安全です。
管理・ベストプラクティス、料金と制限
Glossary は一度作成すれば長期間利用できますが、運用上の注意点やコスト感覚を把握しておくことが重要です。ここでは更新手順、バージョニング、削除時の影響、そして公式料金情報へのリンクを交えて解説します。
1. 更新・バージョン管理
| 操作 | 推奨方法 |
|---|---|
| 内容更新 | gcloud translate glossaries update または同等の API で新しい CSV を指定し上書き。 |
| バージョニング | 名前にバージョン番号を付与（例：my-glossary-v1、my-glossary-v2）し、使用中 Glossary の切り替えを段階的に実施。 |
| 削除前確認 | gcloud translate glossaries describe で依存関係をチェック。削除するとその Glossary を参照している翻訳リクエストはエラーになるので注意。 |
2. 料金体系（2024 年 10 月時点）
| 項目 | 課金方式 |
|---|---|
| Glossary の作成・保管 | 無料（ただし保存先の Cloud Storage に対しては通常通り課金） |
| Glossary 使用時の追加料金 | 標準翻訳料金に加えて 0.10 USD / 1,000 文字[^price] |
シミュレーション例
- 月間翻訳文字数：500,000 文字
- Glossary 利用率：30% → 150,000 文字が追加課金対象
計算式: (150,000 ÷ 1,000) × 0.10 USD = 15 USD の月額追加費用
[^price]: 最新料金は Google Cloud 公式料金ページ（https://cloud.google.com/translate/pricing）をご確認ください。2026 年 4 月時点の情報を基に記載しています。
3. 利用上の制限と対策
| 制限項目 | 内容 | 推奨対応 |
|---|---|---|
| 語彙数上限 | 1 Glossary あたり最大 50,000 語 | カテゴリ別に複数 Glossary を作成し、言語ペアごとに割り当てる |
| 対応言語ペア | 全言語で利用できるわけではなく、サポート対象は公式ページ（https://cloud.google.com/translate/docs/languages）を参照 | 必要な言語が掲載されているか事前に確認 |
| 入力ファイルサイズ | 最大 100 MB、または 1 M 行まで（いずれか先到達した方） | 大規模辞書は分割し、CI パイプラインで順次デプロイ |
| 特殊文字エスケープ | カンマ・タブ・改行・二重引用符は CSV ルールに従う必要がある | テスト用の小さなサンプルでバリデーションを実施後、本番ファイルをアップロード |
4. セキュリティとデータ居住性
- Glossary ファイル自体は Cloud Storage に保存されるため、バケットの IAM ポリシーでアクセス制御を徹底してください。
- データリージョンが重要な規制対象の場合は、Glossary と同じロケーション（例：
asia-northeast1）にバケットと Glossary を配置し、データ転送が発生しないように設計します。
5. CI/CD パイプラインへの組み込み例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
# .github/workflows/glossary.yml name: Deploy Glossary on: push: paths: - 'glossaries/**.csv' jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Cloud SDK uses: google-github-actions/setup-gcloud@v2 with: project_id: ${{ secrets.GCP_PROJECT }} service_account_key: ${{ secrets.GCP_SA_KEY }} - name: Upload CSV to GCS run: | gsutil cp glossaries/my-glossary.csv gs://my-bucket/glossary.csv - name: Create / Update Glossary run: | gcloud translate glossaries create my-glossary \ --project=${{ secrets.GCP_PROJECT }} \ --location=us-central1 \ --input-uri=gs://my-bucket/glossary.csv \ --language-pair=en:ja || \ gcloud translate glossaries update my-glossary \ --project=${{ secrets.GCP_PROJECT }} \ --location=us-central1 \ --input-uri=gs://my-bucket/glossary.csv |
この例は、CSV がリポジトリにプッシュされるたびに自動で Cloud Storage にアップロードし、Glossary を作成または更新します。エラーが出た場合は create が失敗したとみなして update へフォールバックしています。
まとめ
- Glossary は標準 NMT に対する上書き的カスタム辞書で、ブランド名や業界固有語彙の統一に最適です。
- 前提条件は プロジェクト作成・Translation API 有効化・最小権限ロール（admin / user）付与 です。
- CSV/TSV の UTF‑8 エンコーディング、必須ヘッダー、正しいエスケープ を守れば作成はシンプルです。
- Console・gcloud CLI・REST API のいずれでも作成でき、CI/CD への自動化が容易です。
- 翻訳リクエスト時に
glossaryConfigを指定すれば、期待通りの用語置換が確認できます。 - 管理はバージョン命名・上書き更新・削除前依存チェックで安全に行い、料金は追加文字数 0.10 USD/1k 文字（公式ページ参照）です。
- 言語ペアのサポート状況や語彙数上限は 公式ドキュメント を必ず確認し、リージョン・セキュリティ要件に合わせたストレージ設計を行いましょう。
本ガイドを活用して、Google Cloud Translation のカスタム辞書機能を実務で最大限に引き出してください。