# General Translation Integrations: Sanity の設定
URL: https://generaltranslation.com/ja/docs/integrations/sanity/guides/configuring-sanity.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: General Translation の gt-sanity プラグインでロケール、ドキュメントフィルター、フィールドレベルのローカライゼーション、認証情報、シングルトンを設定する方法。

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

## ロケール別に翻訳を閲覧する [#browse-locales]

Sanity では通常、翻訳済みドキュメントはソースドキュメントと並べて表示されます。`gtStructureItems` を使用すると、他の構造項目を維持したまま、翻訳可能なドキュメントタイプごとにロケール別のペインへグループ化できます。

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
    }),
    structureTool({
      structure: (S, context) =>
        S.list()
          .title('Content')
          .items([
            ...gtStructureItems(S, context),
            S.divider(),
            ...S.documentTypeListItems(),
          ]),
    }),
  ],
});
```

ソースロケールのペインには language フィールドを持たないドキュメントも含まれるため、プラグイン導入前に作成されたコンテンツも表示されます。国際化配列を使用してインプレースでローカライズされた型は、翻訳がソースドキュメント内に保持されるためスキップされます。

Studio でロケールごとにグループ化された型のみが必要な場合は、完全な `gtStructure()` リゾルバーを `structureTool` に渡します。

```ts
import { gtStructure } from 'gt-sanity';

structureTool({ structure: gtStructure() });
```

どちらのヘルパーにも `types` を渡すことで、グループ化するドキュメントタイプを指定できます。`sourceTitle` でソースペインの名前を変更し、`localeTitle` でターゲットペインのタイトルをカスタマイズできます。 ([構造ヘルパーのリファレンス](/docs/integrations/sanity/reference/plugin-configuration#structure-helpers)を参照してください) 。

## ソースロケールと対象ロケールを設定する [#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` が優先されます。プラグインは `locales` からソースロケールと重複するエントリを削除するため、共有の `gt.config.json` にデフォルトロケールを安全に含めることができます。

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

フィールドレベルのローカライゼーションは、リファレンスとなる Sanity プラグイン [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array) を基盤としています。`gtPlugin` は `sourceLocale` と `locales` をもとにこれを設定し、ネイティブプラグインは `internationalizedArray*` スキーマ型と Studio の編集 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' }],
},
```

すでにご自身で Studio に `sanity-plugin-internationalized-array` を登録している場合は、現在の setup をそのまま使い、`internationalizedArray` は未設定のままにして、スキーマ型が登録されるのは 1 回だけにしてください。Translation は、どのプラグインインスタンスが型を登録したかに関係なく、保存されている `{ _key, _type, language, value }` データを読み書きするため、GT に必要なのは `translationLevel` (および `translateDocuments`) の設定だけです。

```ts
import { internationalizedArray } from 'gt-sanity';

plugins: [
  internationalizedArray({
    languages: [
      { id: 'en', title: 'English' },
      { id: 'es', title: 'Spanish' },
    ],
    fieldTypes: ['string'],
  }),
  gtPlugin({
    sourceLocale: 'en',
    locales: ['es'],
    translateDocuments: [{ type: 'post' }],
    translationLevel: 'internationalizedArray',
  }),
],
```

両方の戦略を併用するには、`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` から自動的に除外されるため、言語バッジやロケールごとのドキュメントテンプレートは付与されません。インポート時、プラグインはソースドキュメント内の対象ロケールのみを更新し、他のすべての言語はそのまま保持します。

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

## 翻訳対象からフィールドを除外する [#exclude-fields]

スキーマ内のフィールドに印を付けることで、そのコンテンツを翻訳対象から外せます。フィールド定義で `options.gt.exclude` を設定してください。

```ts title="schema/article.ts"
defineField({
  name: 'internalNotes',
  type: 'string',
  options: { gt: { exclude: true } },
});
```

除外されたフィールドは翻訳のために送信されないため、翻訳済みドキュメントでもソース値は変更されずに保持されます。除外は、ネストの深さにかかわらず適用されます。

このプラグインは、標準の Sanity ローカライゼーションプラグインの除外オプションにも対応しているため、スキーマですでにそれらを使用している場合は、重ねて指定する必要はありません。

* `options.documentInternationalization.exclude` from `@sanity/document-internationalization`
* `options.aiAssist.exclude` from `@sanity/assist`
* 旧来の `localize: false` フィールドプロパティ

カスタム型のすべての出現箇所を除外するには、そのオプションを型定義自体に設定します。

```ts title="schema/objects/legalDisclaimer.ts"
export const legalDisclaimer = defineType({
  name: 'legalDisclaimer',
  type: 'object',
  // このタイプが使用されているすべての箇所を除外する
  options: { gt: { exclude: true } },
  fields: [
    defineField({ name: 'jurisdiction', type: 'string' }),
    defineField({ name: 'text', type: 'text' }),
  ],
});
```

IDでドキュメントを対象にするルールや、ロケールごとに値を変換するルール (スラッグの重複排除など) には、代わりにプラグインレベルの [`ignoreFields`, `skipFields`, and `dedupeFields`](/docs/integrations/sanity/reference/plugin-configuration#field-matchers) オプションを使用してください。

## シングルトンドキュメントを設定する [#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: '2025-09-15' });

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

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

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

非公開ドキュメントの運用により、認証されていない公開クエリを防止できますが、認証済みの Studio ユーザーに対する Sanity の権限設定の代わりにはなりません。[Sanity のロールベースアクセス制御](https://www.sanity.io/docs/access-control)でデータセットへのアクセスを制限し、ドキュメントの作成後は一度限りのスクリプトを削除してください。

## オプションの翻訳タブを追加する [#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

## Sitemap

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