# sanity: 設定
URL: https://generaltranslation.com/ja/docs/sanity/guides/configuration.mdx
---
title: 設定
description: Sanity プロジェクト向けに gt-sanity プラグインを設定します
---

## 概要

`gtPlugin` 関数は、翻訳の動作、ロケール設定、ドキュメントの処理方法をカスタマイズするための設定オブジェクトを受け取ります。

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'], // ターゲットロケールに置き換えてください
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
    }),
  ],
});
```

## 基本設定

### ソースロケールとターゲットロケール

ソース言語とターゲットロケールを設定します。

```typescript
gtPlugin({
  sourceLocale: 'en', // コンテンツのソース言語
  locales: ['es', 'zh', 'ja'], // 翻訳対象の言語
});
```


### `gt.config.json` の `defaultLocale` を使う

すでに `gt.config.json` (例: `gt-next` や `gt-react` で使用しているもの) がある場合は、その内容をそのまま plugin の設定にスプレッドできます。`defaultLocale` フィールドは `sourceLocale` のエイリアスとして使用できます。

```typescript
import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig, // { defaultLocale: 'en', locales: ['es', 'zh', 'ja'] }
});
```

`sourceLocale` と `defaultLocale` の両方が指定されている場合は、`sourceLocale` が優先されます。


### 言語フィールド

ドキュメントのロケールを格納するフィールドを指定します。デフォルトは `'language'` です:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale', // デフォルトでは、ドキュメントは 'language' フィールドを使用します。ここでは代わりに 'locale' を使用しています。
});
```


## ドキュメントの絞り込み

### 特定のドキュメントタイプを指定して翻訳する

翻訳を特定のドキュメントタイプに限定します:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'page' }, { type: 'post' }],
});
```


### 特定のドキュメントを翻訳する

対象のドキュメント ID を指定します:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [
    { documentId: 'homepage' },
    { documentId: 'about-page' },
  ],
});
```


## シングルトンドキュメント

シングルトンは、翻訳済みのバリエーションを持つ単一の Sanity ドキュメントです。翻訳版の命名方法を設定します。

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'], // シングルトンドキュメントIDのリスト
  singletonMapping: (docId, locale) => `${docId}-${locale}`, // 翻訳済みシングルトンドキュメントのIDをカスタマイズするオプションの関数
});
```

デフォルトでは、`singletonMapping` が指定されていない限り、シングルトンの翻訳にはランダムに生成された ID が割り当てられます。


## フィールドの除外

翻訳したくない、または GT API に送信したくない一方で、ソースドキュメントから翻訳済みドキュメントにそのままコピーしておく必要があるフィールドです。除外されたフィールドはシリアライズ前に取り除かれるため (つまり、コンテンツが API に送信されることはありません) 、翻訳済みドキュメントの作成後にソースドキュメントから復元されます。

`ignoreFields` は、ソースドキュメントと翻訳済みドキュメントの両方で同じ値にしておくべきものの、翻訳は不要なカテゴリ、タグ、内部メタデータなどのフィールドに使用します。

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  ignoreFields: [
    { fields: [{ property: '$.category' }] },       // すべての言語で同じカテゴリ
    { fields: [{ property: '$..linkType' }] },       // 内部リンクのメタデータ
    { fields: [{ property: '$..frequencies.default' }] },
  ],
});
```

`property` は、ドキュメント内の1つ以上のフィールドにマッチする [JSONPath](https://goessner.net/articles/JsonPath/) 式です。
`type` は、省略可能なパラメータで、無視するフィールドを特定の型にさらに絞り込むために使用します。


## フィールドの重複排除

翻訳したり GT API に送信したりはしたくないものの、ソースドキュメントからはコピーし、翻訳済みドキュメントが最初に作成される際に一意にする必要があるフィールドです。重複排除対象のフィールドはシリアライズ前に取り除かれ、その後、対象ロケールを付加したうえでソースドキュメントから復元されます。

Sanity のスラッグや、そのほかの文字列型の識別子のうち、元の値をベースにしつつ言語ごとに一意である必要があるものには `dedupeFields` を使用します:

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

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

## フィールドをスキップする

翻訳済みドキュメントに自動的に一切コピーしたくないフィールドです。`ignoreFields` (翻訳側にソースの値を残す) とは異なり、`skipFields` は一致したフィールドを翻訳済みドキュメントから完全に削除します。

`skipFields` は、SEO のカノニカル URL、ソース専用のメタデータ、または編集者が言語ごとに手動で設定すべきスラッグなどのフィールドに使用します:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },  // 編集者が言語ごとに slug を手動で設定する
    { fields: [{ property: '$.canonicalUrl' }] },         // ソースにのみ適用される
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],              // ソース専用のデバッグデータ
    },
  ],
});
```

## シリアライズオプション

デフォルトのシリアライズ動作を拡張します：

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalSerializers: {
    // マーク（カスタムアノテーション）用の追加シリアライザー
    marks: {
      link: ({ value, children }) =>
        attachGTData(`<a>${children}</a>`, value, 'markDef'),
      inlineMath: ({ value, children }) =>
        attachGTData(`<span>${children}</span>`, value, 'markDef'),
    },
  },
});
```

詳しくは、[シリアライズガイド](/docs/sanity/guides/serialization)を参照してください。

## 全体の例

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

export default defineConfig({
  name: 'default',
  title: 'My Project',
  projectId: 'your-project-id',
  dataset: 'production',

  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja', 'zh'],
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [
        {
          fields: [{ property: '$.publishedAt' }],
        },
      ],
      dedupeFields: [
        {
          fields: [{ property: '$.slug', type: 'slug' }],
        },
      ],
      skipFields: [
        {
          fields: [{ property: '$.internalNotes' }],
        },
      ],
    }),
  ],

  schema: {
    types: schemaTypes,
  },
});
```

## 次のステップ

* [シリアライズガイド](/docs/sanity/guides/serialization) - カスタムのシリアライズ ルール
* [API リファレンス](/docs/sanity/api/plugin-config) - すべての設定オプション