# sanity: プラグイン設定
URL: https://generaltranslation.com/ja/docs/sanity/api/plugin-config.mdx
---
title: プラグイン設定
description: gtPlugin の設定オプションの API リファレンス
---

## 概要

`gtPlugin` 関数は、Sanity Studio で使用する General Translation を設定します。

```typescript
import { gtPlugin } from 'gt-sanity'

gtPlugin(config: GTPluginConfig)
```


## GTPluginConfig

<TypeTable
  type={{
  sourceLocale: {
    type: 'string',
    description: 'ソース言語コード（例: "en"）。指定がない場合は defaultLocale にフォールバックします。',
    optional: true,
  },
  defaultLocale: {
    type: 'string',
    description: 'sourceLocale のエイリアスです。gt.config.json を直接スプレッドできるよう受け付けられています。両方が設定されている場合は sourceLocale が優先されます。',
    optional: true,
  },
  locales: { type: 'string[]', description: '対象ロケールコードの配列' },
  apiKey: {
    type: 'string',
    description: 'GT APIキー（認証情報ドキュメントを使用する場合は省略可）',
    optional: true,
  },
  projectId: {
    type: 'string',
    description: 'GT project ID（認証情報ドキュメントを使用する場合は省略可）',
    optional: true,
  },
  languageField: {
    type: 'string',
    description: 'ロケールを保存するドキュメントフィールド。デフォルト: "language"',
    optional: true,
  },
  singletons: {
    type: 'string[]',
    description: 'シングルトンとして扱うドキュメントID',
    optional: true,
  },
  singletonMapping: {
    type: '(docId: string, locale: string) => string',
    description:
      '翻訳済みシングルトンIDを生成する関数。デフォルト: "${docId}-${locale}"',
    optional: true,
  },
  ignoreFields: {
    type: 'IgnoreFields[]',
    description: '翻訳対象から除外するフィールド。一致したフィールドはシリアライズ前に削除され、翻訳後にソースドキュメントから復元されます。',
    optional: true,
  },
  dedupeFields: {
    type: 'DedupeFields[]',
    description: '翻訳対象から除外するフィールドで、翻訳済みドキュメントの作成時には対象ロケールを付加したうえでソースドキュメントから初期化されます。',
    optional: true,
  },
  skipFields: {
    type: 'SkipFields[]',
    description: '翻訳済みドキュメントから完全に削除するフィールドです。ignoreFields とは異なり、これらのフィールドは翻訳済みドキュメントに一切含まれません。',
    optional: true,
  },
  translateDocuments: {
    type: "TranslateDocumentFilter[] | string[]",
    description: '翻訳可能なドキュメントを絞り込むフィルターです。フィルターオブジェクトの配列、またはドキュメントタイプ文字列の簡略配列を受け取ります。',
    optional: true,
  },
  secretsNamespace: {
    type: 'string',
    description:
      '認証情報ドキュメントの名前空間。デフォルト: "generaltranslation"',
    optional: true,
  },
  additionalStopTypes: {
    type: 'string[]',
    description: 'シリアライズ時にスキップする追加の型',
    optional: true,
  },
  additionalSerializers: {
    type: 'Record<string, Serializer>',
    description: 'ブロック型用のカスタムHTMLシリアライザー',
    optional: true,
  },
  additionalDeserializers: {
    type: 'Record<string, Deserializer>',
    description: 'カスタムHTMLデシリアライザー',
    optional: true,
  },
  additionalBlockDeserializers: {
    type: 'BlockDeserializer[]',
    description: 'カスタムのブロックレベルデシリアライザー',
    optional: true,
  },
  customMapping: {
    type: "Record<string, string | Partial<LocaleProperties>>",
    description: '標準以外のロケールコード向けのカスタムロケールマッピング',
    optional: true,
  },
  showDocumentInternationalization: {
    type: 'boolean',
    description: 'true の場合（デフォルト）、言語バッジ、翻訳メニュー、言語ごとの templates を備えた @sanity/document-internationalization プラグインを自動的に追加します。translateDocuments が必要です。',
    optional: true,
  },
}}
/>

## IgnoreFields

翻訳されず、API にも送信されない一方で、ソースドキュメントから翻訳先へコピーされるフィールドです。すべての言語で同じ値にする必要があるカテゴリ、タグ、内部メタデータなどのフィールドに使用します。

```typescript
type IgnoreFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```


### 例

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  ignoreFields: [
    // すべての翻訳済みドキュメントに category をそのままコピーする
    {
      fields: [{ property: '$.category' }],
    },
    // 記事にのみこれらのフィールドをそのままコピーする
    {
      documentId: 'article',
      fields: [{ property: '$.tags' }, { property: '$.author' }],
    },
  ],
});
```


## DedupeFields

翻訳も API への送信もされず、翻訳済みドキュメントが最初に作成される際に、ソースドキュメントから対象ロケールを付加したうえでコピーされるフィールドです。Sanity のスラッグのように、最初はソース由来でありつつ、翻訳済みドキュメントごとに一意である必要があるフィールドに使用します。

```typescript
type DedupeFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```

### 例

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'fr'],
  dedupeFields: [
    // "about" は "about-es" と "about-fr" になります
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
  ],
});
```

Sanity の スラッグ フィールドでは、プラグイン が スラッグ オブジェクトの `current` の値を更新します。たとえば、スペイン語のドキュメントが作成されると、`{ _type: 'slug', current: 'about' }` が `{ _type: 'slug', current: 'about-es' }` になります。後で Editor が翻訳後のスラッグを変更した場合、以後の翻訳インポートではその編集後の値が保持されます。

## SkipFields

翻訳済みドキュメントから完全に削除されるフィールドです。`ignoreFields` とは異なり、これらのフィールドは訳文には一切含まれません。SEO のカノニカル URL、ソース専用のメタデータ、または編集者が言語ごとに手動で設定すべきスラッグのようなフィールドに使用します。

```typescript
type SkipFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```

### 例

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  skipFields: [
    // Editorが言語ごとにスラッグを手動で設定する
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
    // Remove source-only debug data from homepage translations
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],
    },
  ],
});
```

## TranslateDocumentFilter

翻訳可能なドキュメントを絞り込みます。

```typescript
type TranslateDocumentFilter = {
  documentId?: string; // 特定のドキュメントID
  type?: string; // ドキュメントの種類
};
```


### 例

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: [
    { type: 'article' },
    { type: 'page' },
    { documentId: 'homepage' },
  ],
});
```


## シリアライザー

Sanity のブロックを HTML に変換するカスタム関数:

```typescript
type Serializer = (props: {
  value: any;
  isInline?: boolean;
  children?: string;
}) => string;
```


### 例

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalSerializers: {
    link: ({ value, children }) =>
      attachGTData(`<a>${children}</a>`, value, 'markDef'),
  },
});
```


## デフォルトの停止タイプ

これらの型は保持されますが、翻訳対象としては送信されません。

```typescript
const defaultStopTypes = [
  'reference',
  'crossDatasetReference',
  'date',
  'datetime',
  'file',
  'geopoint',
  'image',
  'number',
  'slug',
  'url',
];
```

`additionalStopTypes` を使ってさらに追加します:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalStopTypes: ['codeBlock', 'mathFormula'],
});
```


## 完全な使用例

```typescript title="sanity.config.ts"
import { defineConfig } from 'sanity';
import { attachGTData, gtPlugin } from 'gt-sanity';

export default defineConfig({
  plugins: [
    gtPlugin({
      // 必須
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja'],

      // ドキュメント処理
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      singletonMapping: (id, locale) => `${id}_${locale}`,

      // フィルタリング
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [{ fields: [{ property: '$.publishedAt' }] }],
      dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }],
      skipFields: [{ fields: [{ property: '$.internalNotes' }] }],

      // シリアライズ - 内容を十分に理解している場合のみ使用してください！
      additionalSerializers: {
        // マーク（カスタムアノテーション）用の追加シリアライザー
        marks: {
          link: ({ value, children }) =>
            attachGTData(`<a>${children}</a>`, value, 'markDef'),
          inlineMath: ({ value, children }) =>
            attachGTData(`<span>${children}</span>`, value, 'markDef'),
        },
      },
    }),
  ],
});
```

## 次のステップ

* [設定ガイド](/docs/sanity/guides/configuration) - 設定方法
* [シリアライズガイド](/docs/sanity/guides/serialization) - カスタムシリアライズ