# General Translation Integrations: クイックスタート
URL: https://generaltranslation.com/ja/docs/integrations/sanity/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: gt-sanity をインストールし、General Translation プラグインを Sanity Studio に追加して、最初のドキュメントを翻訳します。

`gt-sanity` プラグインを使うと、Sanity Studio 内からドキュメントを翻訳できます。ドキュメント単位とフィールドレベルのローカライゼーションに対応しており、このクイックスタートではデフォルトのドキュメント単位のセットアップを使用します。この場合、各翻訳は `language` フィールドを持つ個別のドキュメントとなり、`@sanity/document-internationalization` が管理する `translation.metadata` ドキュメントも使用されます。

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

必要なもの:

* Sanity Studio 6.9.2 以降。Sanity 6.0～6.8 の Studio は引き続き `@sanity/ui` 3 世代を使用しているため、`gt-sanity` 3.1.x を使用してください。
* React 19.2.0 以降。
* Node.js 22.12 以降。
* 既存の Sanity プロジェクト。
* General Translation の [プロジェクト ID](/docs/platform/dashboard/get-started) と本番環境用の [API キー](/docs/platform/dashboard/reference/api-keys)。

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

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

Sanity Studio プロジェクトにこのプラグインをインストールします。`gt-sanity` は、`@sanity/ui`、`@sanity/icons`、`@sanity/schema`、`@sanity/mutator` を Studio のピア依存関係として解決するため、各 Studio Runtime シングルトンのコピーはツリー内で 1 つだけになります。Sanity 6.9.2 以降の Studio には、すでに4つすべてが含まれています。

<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: '2025-09-15' });

client.createOrReplace({
  // _id の先頭の `.` により、公開データセットでもドキュメントは非公開になります。
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslationSettings',
  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` を削除してください。

<Callout type="warn">
  先頭の `.` により、このドキュメントは認証されていない公開データセットクエリの対象外になりますが、認証済みの Studio アクセスには引き続き Sanity プロジェクトのロールが適用されます。[Sanity のロールベースアクセス制御](https://www.sanity.io/docs/access-control)を使用して、インテグレーションを必要とするユーザーだけがデータセットを読み取れるようにし、スクリプトや認証情報は絶対に commit しないでください。
</Callout>

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

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

このドキュメント単位のセットアップでは、プラグインが完了した翻訳をポーリングして下書きとして自動的にインポートします。参照のパッチ適用と公開はデフォルトで無効です。ダイアログのコントロールを使用するか、[`autoPatchReferences`](/docs/integrations/sanity/reference/plugin-configuration#auto-patch-references) と [`autoPublish`](/docs/integrations/sanity/reference/plugin-configuration#auto-publish) で初期状態を設定してください。

Sanity の **Drafts** パースペクティブでインポートしたドキュメントを確認し、公開済みコンテンツのみを対象とするフロントエンドからクエリを実行する前に公開してください。

 (詳しくは、[コンテンツを翻訳する](/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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.