# General Translation Integrations: Sanity の設定
URL: https://generaltranslation.com/ja/docs/integrations/sanity/guides/configuring-sanity.mdx
---
title: Sanity の設定
description: "General Translation の gt-sanity プラグインを設定する方法。このガイドでは、ロケール、ドキュメントフィルター、フィールドレベルのローカライゼーション、認証情報、language フィールド、シングルトンについて説明します。"
related:
  links:
    - /docs/integrations/sanity/guides/translating-content
    - /docs/integrations/sanity/guides/managing-translations
    - /docs/integrations/sanity/guides/querying-translations

---

`gtPlugin` 関数を使って、Sanity Studio 内での General Translation の動作を設定します。

このガイドでは、よく使われるオプションを紹介します。完全な一覧については、[プラグイン設定リファレンス](/docs/integrations/sanity/reference/plugin-configuration)を参照してください。

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

Studio の設定に `gtPlugin` を追加します。この手順は [Quickstart](/docs/integrations/sanity/quickstart) でも説明しています。

```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' }],
    }),
  ],
});
```

## ソースロケールと対象ロケールを設定する [#set-locales]

ソース言語には `sourceLocale` を、対象言語には `locales` を使用します。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
});
```

すでに `gt.config.json` がある場合は、それをプラグイン設定にスプレッドできます。`defaultLocale` は `sourceLocale` のエイリアスとして使用できます。

```ts title="sanity.config.ts"
import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig,
});
```

ソースロケールは、`sourceLocale`、次に `defaultLocale`、最後にライブラリのデフォルトの順で決定されます。`sourceLocale` と `defaultLocale` の両方が設定されている場合は、`sourceLocale` が優先されます。

## 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` を設定し、スキーマでも同じ名前を使用してください。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale',
});
```

## 翻訳するドキュメントを選択 [#choose-documents]

`translateDocuments` を使用して、翻訳するドキュメントを絞り込めます。ドキュメントタイプのフィルター、ドキュメント ID のフィルター、または省略記法のタイプ文字列を指定できます。

```ts
// ドキュメントタイプ別
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'page' }, { type: 'post' }],
});
```

```ts
// 特定のドキュメントIDで指定
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ documentId: 'homepage' }, { documentId: 'about-page' }],
});
```

```ts
// 短縮形の型文字列
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: ['article', 'page'],
});
```

文字列エントリは `{ type: '<string>' }` として扱われます。`showDocumentInternationalization` は `type` エントリを使って、どのスキーマ型に言語バッジとテンプレートを適用するかを判断するため、これらの機能を有効にするにはドキュメント型フィルタが必要です. 

## フィールドレベルのローカライゼーションを設定する [#field-level]

デフォルトでは、`gt-sanity` はドキュメントレベルで翻訳を行い、ロケールごとに 1 つのドキュメントを作成します。フィールドレベルのローカライゼーションでは、各ロケールの値を同じドキュメント内に国際化配列 (`[{ _key, _type, language, value }]` — [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array) と同じ形式なので、既存データを移行する必要はありません) として保存します。

`internationalizedArray` (またはその別名である `fieldLevelLocalization`) でスキーマ生成を有効にし、その後 `translationLevel` を `'internationalizedArray'` に設定します。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'post' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'internationalizedArray',
});
```

このプラグインは、`sourceLocale` と `locales` から `internationalizedArray*` スキーマ型を生成し、あわせてロケールごとにインラインで編集できる UI も提供します。生成された型をスキーマで使用してください。

```ts
defineField({
  name: 'title',
  type: 'internationalizedArrayString',
});
```

デフォルトでは、このプラグインは `string` 型と `text` 型を生成します。`fieldTypes` を使って、`block` (Portable Text) やカスタムオブジェクト定義を追加してください。

```ts
internationalizedArray: {
  enabled: true,
  fieldTypes: ['string', 'text', 'block', { name: 'seo', type: 'seoFields' }],
},
```

両方の戦略を併用するには、`translationLevel` を `'mixed'` に設定し、フィールドレベルのドキュメントタイプを `fieldLevelDocuments` に指定します。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'mixed',
  fieldLevelDocuments: [{ type: 'siteSettings' }],
});
```

インプレースでローカライズされるドキュメントタイプは `@sanity/document-internationalization` から自動的に自動的に除外されるため、言語バッジやロケールごとのドキュメントテンプレートは付与されません。インポート時、プラグインは source document 内の対象ロケールのみを更新し、他のすべての言語はそのまま保持します。

各フィールドレベルのオプションについては、[プラグイン設定リファレンス](/docs/integrations/sanity/reference/plugin-configuration#field-level)を参照してください。

## シングルトンドキュメントを設定する [#singletons]

`singletons` は、サイト設定やナビゲーションのように、サイトごとに1つしか存在しないドキュメントに使用します。`singletonMapping` は、翻訳後のシングルトンドキュメントの ID を、元の ID とロケールからどのように導き出すかを制御します。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'],
  singletonMapping: (sourceDocumentId, locale) => `${sourceDocumentId}-${locale}`,
});
```

`singletonMapping` を省略すると、デフォルトでは `sourceDocumentId` と `locale` は `` `${sourceDocumentId}-${locale}` `` にマッピングされます (例: `siteSettings-es`) 。

## 認証情報を保存する [#store-credentials]

プラグインは、`_id` が `secretsNamespace` (デフォルトは `generaltranslation.secrets`) と一致する非公開の Sanity ドキュメントから、API Key と project ID を読み取ります。これを一度限りのスクリプトで作成してください。

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

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

client.createOrReplace({
  _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
```

`secret` フィールドは API Key として使用され、`project` フィールドは project ID として使用されます。別のドキュメントから認証情報を読み込むには、`secretsNamespace` をそのドキュメントの `_id` に設定してください。

`apiKey` と `projectId` を `gtPlugin` に直接渡すこともできますが、認証情報をソース管理に含めないため、secrets ドキュメントの使用を推奨します。両方が存在する場合、Runtime では secrets ドキュメントが優先されます。

## オプションの翻訳タブを追加する [#translations-tab]

**Translate** ドキュメントアクションは自動的に追加されます。ドキュメントエディタ内にも翻訳タブを表示するには、`structureTool` に `TranslationsTab` を追加します。

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

export default defineConfig({
  plugins: [
    structureTool({
      defaultDocumentNode: (S) =>
        S.document().views([
          S.view.form(),
          S.view.component(TranslationsTab).title('General Translation'),
        ]),
    }),
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
    }),
  ],
});
```
## Next steps

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