# General Translation Integrations: クイックスタート
URL: https://generaltranslation.com/ja/docs/integrations/sanity/quickstart.mdx
---
title: クイックスタート
description: gt-sanity をインストールし、General Translation プラグインを Sanity Studio に追加して、最初のドキュメントを翻訳します。
related:
  links:
    - /docs/integrations/sanity/guides/translating-content
    - /docs/integrations/sanity/guides/managing-translations
    - /docs/integrations/sanity/guides/querying-translations
    - /docs/integrations/sanity/guides/configuring-sanity

---

General Translation の `gt-sanity` プラグインを使うと、Sanity Studio 内から Sanity ドキュメントを翻訳できます。

このプラグインはドキュメントレベルのローカライゼーションを採用しています。各翻訳は、`language: "es"` のような language フィールドを持つ個別の Sanity ドキュメントとして保存されます。翻訳は、`@sanity/document-internationalization` が管理する `translation.metadata` ドキュメントを通じてソースドキュメントに関連付けられます。

## 始める前に [#before-start]

必要なもの:

* Sanity Studio 5.0.0 以降。
* React 19.2.0 以降。
* 既存の Sanity プロジェクト。
* General Translation の [プロジェクト ID](/docs/platform/dashboard/get-started) と本番環境用の [API キー](/docs/platform/dashboard/reference/api-keys)。

## クイックスタート [#quickstart]

### 1. `gt-sanity` をインストール [#install]

Sanity Studio プロジェクトにこのプラグインをインストールします。

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

### 2. プラグインを追加する [#add-plugin]

`gtPlugin` を `sanity.config.ts` に追加します。source ロケール、対象ロケール、翻訳するドキュメントタイプを設定します。

```ts 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` プラグインを自動的に追加します。これにより、言語バッジ、ドキュメントツールバーの翻訳メニュー、言語ごとのドキュメントテンプレートが利用可能になります。これを無効にするには、`showDocumentInternationalization: false` を設定してください。

### 3. language フィールドを追加する [#language-field]

翻訳する各ドキュメントタイプには、language フィールドが必要です。デフォルトの名前は `language` です。

```ts 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`](/docs/integrations/sanity/reference/plugin-configuration#language-field)を設定した場合は、schemaでは`language`ではなくその名前を使用してください。

### 4. 認証情報を保存する [#credentials]

プラグインは、非公開の Sanity ドキュメントから General Translation の API キーとプロジェクト ID を読み取ります。Studio フォルダー内に、一時的な `populateSecrets.js` ファイルを作成してください。

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

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

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

認証情報を使ってスクリプトを実行します:

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

ドキュメントの`_id`は、プラグインの`secretsNamespace` (デフォルトは`generaltranslation.secrets`) と一致している必要があります。プラグインは、`secret`フィールドをAPI キー、`project`フィールドをプロジェクト IDとして読み取ります。

Studio の Vision ツールでドキュメントが存在することを確認します。

```text
*[_id == 'generaltranslation.secrets']
```

複数のデータセットを使用している場合は、データセットごとにこの手順を繰り返してください。確認が済んだら、`populateSecrets.js` を削除してください。

### 5. ドキュメントを翻訳する [#translate-document]

1. Sanity Studio でソース言語のドキュメントを開きます。
2. ドキュメントのアクションバーで **翻訳** をクリックします。
3. 対象のロケールを選択します。
4. **翻訳を生成** をクリックします。

このドキュメントダイアログでは、プラグインが完了した翻訳をポーリングして自動的にインポートします。インポート後は、このダイアログで auto-import、auto-patch、auto-publish がデフォルトで有効になっているため、ドキュメント参照にパッチを適用し、翻訳済みドキュメントを公開します。

詳しくは、[コンテンツを翻訳する](/docs/integrations/sanity/guides/translating-content) と [翻訳を管理する](/docs/integrations/sanity/guides/managing-translations) の各ガイドを参照してください。

### 6. 翻訳済みコンテンツをクエリする [#query-content]

翻訳は、language フィールドを持つ別々のドキュメントとして保存されます。翻訳済みコンテンツを取得するには、language フィールドで絞り込みます。

<Tabs items={['ソースクエリ', 'ローカライズされたクエリ']}>
  <Tab value="Source query">
    ```text
    // ソース言語のドキュメントでは、デフォルトで language フィールドは設定されません
    *[_type == "article" && !defined(language)]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Localized query">
    ```text
    // スペイン語の記事を取得
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }
    ```
  </Tab>
</Tabs>

ほかのクエリパターンについては、[翻訳のクエリ](/docs/integrations/sanity/guides/querying-translations)を参照してください。
## Next steps

- /docs/integrations/sanity/guides/translating-content
- /docs/integrations/sanity/guides/managing-translations
- /docs/integrations/sanity/guides/querying-translations
- /docs/integrations/sanity/guides/configuring-sanity