# sanity: Sanity クイックスタート
URL: https://generaltranslation.com/ja/docs/sanity/guides/quickstart.mdx
---
title: Sanity クイックスタート
description: gt-sanity を使用して General Translation を Sanity CMS に統合します
---

**前提条件:** Sanity Studio v5+、React 19+、既存の Sanity プロジェクト

<Callout type="warn">
  **スキーマとフロントエンド側の変更が必要です。** 翻訳する各ドキュメントタイプでは、スキーマに `language` フィールドを含める必要があります。詳しくは [language フィールドのセットアップ](/docs/sanity#language-field) を参照してください。
  翻訳は別個のドキュメントとして保存されるため、適切な言語版を取得できるようにフロントエンドのクエリを更新する必要があります。
  例については、以下の [翻訳済みコンテンツのクエリ](#querying-translated-content) を参照してください。
</Callout>

## インストール

Sanity Studio のディレクトリで `gt-sanity` パッケージをインストールします。

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-sanity
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-sanity
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-sanity
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-sanity
    ```
  </Tab>
</Tabs>

## 設定

<Steps>
  <Step title="Sanity の設定にプラグインを追加する">
    ```typescript title="sanity.config.ts"
    import { defineConfig } from 'sanity'
    import { gtPlugin } from 'gt-sanity'

    export default defineConfig({
      // ... 既存の設定
      plugins: [
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja'], // 対象ロケールに置き換えてください
          translateDocuments: [{ type: 'article' }, { type: 'page' }], // 翻訳を有効にするドキュメントタイプ
        })
      ]
    })
    ```

    `translateDocuments` を指定すると、プラグインは @sanity/document-internationalization の機能 (言語バッジ、ドキュメントツールバーの翻訳メニュー、言語ごとのドキュメント template) を自動的に追加します。これを無効にするには、`showDocumentInternationalization: false` を設定します。
  </Step>

  <Step title="スキーマに language フィールドを追加する">
    翻訳するすべてのドキュメントタイプには `language` フィールドが必要です。

    ```typescript title="schema/article.ts"
    import { defineField, defineType } from 'sanity'

    export const articleType = defineType({
      name: 'article',
      title: 'Article',
      type: 'document',
      fields: [
        // ... 既存のフィールド
        defineField({
          name: 'language',
          type: 'string',
          readOnly: true,
          hidden: true,
        }),
      ],
    })
    ```

    プラグインオプションでカスタムの `languageField` を設定している場合は、`'language'` の代わりにその名前を使用します。
  </Step>

  <Step title="API 認証情報を設定する">
    Studio フォルダに、次の内容で `populateSecrets.js` というファイルを作成します。

    ```javascript title="populateSecrets.js"
    import { getCliClient } from 'sanity/cli';

    const client = getCliClient({ apiVersion: '2026-04-06' });

    client.createOrReplace({
      // この _id に含まれる `.` により、このドキュメントは非公開になります
      // 公開データセットであっても同様です。
      _id: 'generaltranslation.secrets',
      _type: 'generaltranslationSettings',
      secret: process.env.GT_API_KEY,
      project: process.env.GT_PROJECT_ID,
    });
    ```

    次に、[dash.generaltranslation.com](https://dash.generaltranslation.com) で本番用 API キーを取得します。

    認証情報を指定してスクリプトを実行します。

    ```bash
    GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token
    ```

    Studio の Vision Tool でドキュメントが作成されたことを確認し、`*[_id == 'generaltranslation.secrets']` をクエリします。

    注: データセットが複数ある場合は、そのすべてに対してこの操作を行う必要があります。

    データセット内でドキュメントが見つかったら、`populateSecrets.js` を削除します。

    <Callout type="warn">
      これらの認証情報は Sanity データベースに保存されます。デフォルトでは `generaltranslation.secrets` ドキュメントに保存され、このドキュメントは公開データセットであっても非公開です。
      ただし、Studio の認証済みユーザーに公開されることが懸念される場合は、[ロールベースのアクセス制御](https://www.sanity.io/docs/access-control) でこのパスへのアクセスを制御できます。
    </Callout>
  </Step>

  <Step title="（任意）専用の Translations タブを追加する">
    プラグインは、ダイアログを開く **Translate** アクションをすべてのドキュメントに自動的に追加します。専用のタブビューも必要な場合は、ドキュメントビューに `TranslationsTab` コンポーネントを追加します。

    ```typescript title="sanity.config.ts"
    import { defineConfig } from 'sanity'
    import { structureTool } from 'sanity/structure'
    import { gtPlugin, TranslationsTab } from 'gt-sanity'

    export default defineConfig({
      // ... 設定
      plugins: [
        structureTool({
          structure: (S) =>
            S.list()
              .title('Content')
              .items(S.documentTypeListItems()),
          defaultDocumentNode: (S, { schemaType }) => {
            return S.document().views([
              S.view.form(),
              S.view
                .component(TranslationsTab)
                .title('General Translation')
            ])
          }
        }),
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja']
        })
      ]
    })
    ```
  </Step>
</Steps>

## 使い方

設定が完了すると、Sanity Studio から直接ドキュメントを翻訳できます。

1. Studio で任意のドキュメントを開きます
2. ドキュメントのアクションバーにある **Translate** ボタンをクリックします — ダイアログが開きます
3. 対象の言語を選択します
4. **Generate Translations** をクリックして、コンテンツを翻訳に送信します
5. デフォルトでは、プラグイン が翻訳の準備ができ次第、自動的にドキュメントへ取り込みます。
6. また、取り込まれたドキュメントは他のドキュメントへの参照がないか自動的にスキャンされ、それらのドキュメントの正しい翻訳先を指すよう自動的にパッチされます。

## 翻訳済みコンテンツのクエリ

plugin は、翻訳を `language` フィールドを持つ別個のドキュメントとして保存します ([`languageField`](/docs/sanity/api/plugin-config) で設定可能) 。ソースコンテンツに対する既存の GROQ クエリは、変更せずそのまま使えます。

翻訳済みコンテンツを取得するには、`language` フィールドで絞り込みます。

<Tabs items={["基本クエリ", "ローカライズ済みクエリ"]}>
  <Tab value="基本クエリ">
    既存のクエリはそのままで問題ありません。変更は不要です。

    ```plaintext
    // すべての記事を取得（ソース言語のドキュメントを返す）
    *[_type == "article"]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="ローカライズ済みクエリ">
    翻訳済みドキュメントを取得するには、`language` フィルターを追加します。

    ```plaintext
    // スペイン語の記事を取得
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }

    // 特定の言語の特定の記事を取得
    *[_type == "article" && slug.current == "hello-world" && language == "es"][0]{
      title,
      body
    }

    // 任意の言語の記事を取得
    *[_type == "article"]{
      title,
      slug,
      body,
      language
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  ソースドキュメントでは、デフォルトで `language` フィールドは設定されません。翻訳とあわせてソースコンテンツもクエリするには、`language` がソースロケールであるか、未設定のドキュメントを対象に絞り込めます: `language == "en" || !defined(language)`.
</Callout>

## 次のステップ

* [設定ガイド](/docs/sanity/guides/configuration) - plugin の動作をカスタマイズ
* [シリアライズガイド](/docs/sanity/guides/serialization) - シリアライズのカスタムルール
* [API リファレンス](/docs/sanity/api/plugin-config) - 設定オプションの全一覧