# General Translation Integrations: Sanity プラグインの設定 URL: https://generaltranslation.com/ja/docs/integrations/sanity/reference/plugin-configuration.mdx --- title: Sanity プラグインの設定 description: Sanity Studio 向けの General Translation `gt-sanity` プラグインを設定します。`gtPlugin` の API リファレンス。 --- `gtPlugin` 関数を使用して、Sanity Studio で General Translation を設定します。1 つのオプションオブジェクトを渡します。 ```ts title="sanity.config.ts" import { gtPlugin } from 'gt-sanity'; gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], translateDocuments: [{ type: 'article' }], }); ``` ## オプション [#options] | オプション | 説明 | 型 | 任意 | デフォルト | | ----------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------- | --- | ------------------------------------- | | [`sourceLocale`](#source-locale) | `en` などのソース言語のロケールコード。 | `string` | はい | `defaultLocale`、次にライブラリのデフォルト値 | | [`defaultLocale`](#default-locale) | `gt.config.json` の展開用の `sourceLocale` の エイリアス。 | `string` | はい | — | | [`locales`](#locales) | 対象のロケールコード。 | `string[]` | いいえ | — | | [`customMapping`](#custom-mapping) | カスタムのロケールコードの mapping とプロパティのオーバーライド。 | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | はい | — | | [`apiKey`](#api-key) | General Translation の API キー。 | `string` | はい | Secrets ドキュメント | | [`projectId`](#project-id) | General Translation の プロジェクト ID。 | `string` | はい | Secrets ドキュメント | | [`secretsNamespace`](#secrets-namespace) | 非公開認証情報ドキュメントの `_id`。 | `string` | はい | `generaltranslation.secrets` | | [`languageField`](#language-field) | ロケールを保存するドキュメントフィールド。 | `string` | はい | `language` | | [`translateDocuments`](#translate-documents) | 翻訳可能なドキュメントを絞り込みます。 | `TranslateDocumentFilter[] \| string[]` | はい | `[]` | | [`singletons`](#singletons) | シングルトン として扱うドキュメント ID。 | `string[]` | はい | `[]` | | [`singletonMapping`](#singleton-mapping) | ソース ID とロケールを翻訳済み シングルトン ID に対応付けます。 | `(sourceDocumentId: string, locale: string) => string` | はい | `` `${sourceDocumentId}-${locale}` `` | | [`showDocumentInternationalization`](#show-doc-i18n) | `@sanity/document-internationalization` を自動で追加します。 | `boolean` | はい | `true` | | [`internationalizedArray`](#internationalized-array) | 国際化配列を使用したフィールドレベルのローカライゼーションを設定します。 | `GTFieldLevelLocalizationConfig` | はい | — | | [`fieldLevelLocalization`](#field-level-localization) | `internationalizedArray` の エイリアス。 | `GTFieldLevelLocalizationConfig` | はい | — | | [`translationLevel`](#translation-level) | ドキュメントレベル、フィールドレベル、または混在の翻訳を選択します。 | `'document' \| 'internationalizedArray' \| 'mixed'` | はい | `'document'` | | [`fieldLevelDocuments`](#field-level-documents) | mixed モードでフィールドレベルのローカライゼーションを使用するドキュメントタイプ。 | `TranslateDocumentFilter[] \| string[]` | はい | `[]` | | [`ignoreFields`](#ignore-fields) | 翻訳せずにソースからコピーするフィールド。 | `FieldMatcher[]` | はい | `[]` | | [`dedupeFields`](#dedupe-fields) | ソースからコピーし、ロケールごとに一意化するフィールド。 | `FieldMatcher[]` | はい | `[]` | | [`skipFields`](#skip-fields) | 翻訳済みドキュメントから削除するフィールド。 | `FieldMatcher[]` | はい | `[]` | | [`additionalStopTypes`](#additional-stop-types) | 翻訳せずに保持する追加の schema タイプ。 | `string[]` | はい | `[]` | | [`additionalSerializers`](#additional-serializers) | マークおよびブロックタイプ用のカスタム HTML シリアライザー。 | `Partial` | はい | `{}` | | [`additionalDeserializers`](#additional-deserializers) | カスタム HTML デシリアライザー。 | `CustomDeserializers` | はい | `{}` | | [`additionalBlockDeserializers`](#additional-block-deserializers) | カスタム Portable Text ブロック デシリアライザー ルール。 | `unknown[]` | はい | `[]` | ## ロケールオプション [#locale-options] ### `sourceLocale` [#source-locale] **型** `string` · **任意** · **デフォルト** `defaultLocale`、その次にライブラリのデフォルト `en` などのソース言語コードです。プラグインは、ソースロケールを次の順序で解決します: `sourceLocale`、次に `defaultLocale`、最後に `generaltranslation` ライブラリのデフォルト。 ### `defaultLocale` [#default-locale] **型** `string` · **省略可能** `sourceLocale` のエイリアスです。`gt.config.json` をそのままプラグインにスプレッドできるよう、この名前でも受け付けています。両方が設定されている場合は、`sourceLocale` が優先されます。 ```ts import gtConfig from './gt.config.json'; gtPlugin({ ...gtConfig }); ``` ### `locales` [#locales] **型** `string[]` · **必須** 翻訳先のロケールコードです。たとえば `['es', 'fr', 'ja']` などです。 ### `customMapping` [#custom-mapping] **型** `CustomMapping` · **任意** ロケールコードから名前へのカスタムマッピング、またはロケールのプロパティを上書きする設定です。`generaltranslation` ライブラリにそのまま渡されます。詳しくは [CustomMapping](/docs/platform/core/reference/types/custom-mapping) を参照してください。 ## 認証情報 [#credentials] デフォルトでは、プラグインは非公開の Sanity ドキュメントから認証情報を読み込みます。[認証情報を保存する](/docs/integrations/sanity/guides/configuring-sanity#store-credentials)を参照してください。 ### `apiKey` [#api-key] **型** `string` · **任意** · **デフォルト** secrets ドキュメントから読み込み General Translation の API キーです。設定すると、起動時にライブラリへ渡されます。secrets ドキュメントが存在する場合、実行時にはその `secret` フィールドが優先されます。API キーをソース管理に含めないため、secrets ドキュメントを使うことを推奨します。 ### `projectId` [#project-id] **型** `string` · **任意** · **デフォルト** secrets ドキュメントから読み込み General Translation の プロジェクト ID です。secrets ドキュメントがある場合、Runtime ではその `project` フィールドが優先されます。 ### `secretsNamespace` [#secrets-namespace] **型** `string` · **任意** · **デフォルト** `generaltranslation.secrets` 認証情報を保持する非公開の Sanity ドキュメントの `_id` です。プラグインはこのドキュメントを `_id` で取得し、`secret` フィールドを API キーとして、`project` フィールドをプロジェクト ID として読み取ります。`_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, }); ``` ## ドキュメントオプション [#document-options] ### `languageField` [#language-field] **Type** `string` · **Optional** · **Default** `language` 各ドキュメントのロケールを保存するためのドキュメントフィールドです。翻訳対象のすべてのドキュメントタイプにこの名前のフィールドを追加し、特定のロケールを取得する際はそれを query してください。 ### `translateDocuments` [#translate-documents] **型** `TranslateDocumentFilter[] | string[]` · **任意** · **デフォルト** `[]` 翻訳可能なドキュメントを絞り込みます。フィルタオブジェクト、または省略記法の型文字列を受け取ります。各 string のエントリ `'article'` は `{ type: 'article' }` に正規化され、`documentId` または `type` を持たないエントリは破棄されます。 ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], translateDocuments: [ { type: 'article' }, { documentId: 'homepage' }, 'page', // { type: 'page' } の短縮形 ], }); ``` `TranslateDocumentFilter` は次のような形です: ```ts type TranslateDocumentFilter = { documentId?: string; // _id で特定のドキュメントに一致 type?: string; // スキーマタイプのすべてのドキュメントに一致 }; ``` `type` エントリは、[`showDocumentInternationalization`](#show-doc-i18n) を有効にするスキーマタイプも決定します。 ### `singletons` [#singletons] **型** `string[]` · **省略可能** · **デフォルト** `[]` サイト設定やナビゲーションなど、シングルトンとして扱うドキュメント ID です。それらの翻訳ドキュメント ID は、[`singletonMapping`](#singleton-mapping) から導出されます。 ### `singletonMapping` [#singleton-mapping] **型** `(sourceDocumentId: string, locale: string) => string` · **任意** · **デフォルト** `` `${sourceDocumentId}-${locale}` `` シングルトンのsource document IDとロケールを、翻訳後のシングルトンのdocument IDにマッピングします。デフォルトでは規則的に決まるため、`siteSettings` はスペイン語なら `siteSettings-es` になります。 ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], singletons: ['siteSettings'], singletonMapping: (sourceDocumentId, locale) => `${sourceDocumentId}_${locale}`, }); ``` ### `showDocumentInternationalization` [#show-doc-i18n] **型** `boolean` · **省略可能** · **デフォルト** `true` `true` の場合、このプラグインは `@sanity/document-internationalization` プラグインを追加し、言語バッジ、翻訳メニュー、言語ごとのドキュメントテンプレートを有効にします。このとき、[`translateDocuments`](#translate-documents) の `type` エントリを schema type とし、`[sourceLocale, ...locales]` をサポート対象の言語として使用するため、`translateDocuments` にドキュメントタイプが含まれている場合にのみ機能します。国際化配列を使ってインプレースでローカライズされたドキュメントタイプは、自動的に除外されます。国際化を自分で管理する場合は、`false` に設定してください。 ## フィールドレベルのローカライゼーション [#field-level] フィールドレベルのローカライゼーションでは、各ロケールの値を1つのドキュメント内に国際化配列として保存します。保存されるデータは `sanity-plugin-internationalized-array` と同じ `{ _key, _type, language, value }` という項目構造を使用するため、既存の国際化配列コンテンツを移行する必要はありません。 ### `internationalizedArray` [#internationalized-array] **型** `GTFieldLevelLocalizationConfig` · **省略可能** フィールドレベルのローカライゼーションで使用するスキーマ型と Studio の入力コンポーネントを設定します。ロケールの識別情報は常に `sourceLocale` と `locales` から取得されます。 ```ts type GTFieldLevelLocalizationConfig = { enabled?: boolean; // デフォルト: false fieldTypes?: FieldLevelFieldType[]; // デフォルト: ['string', 'text'] languageTitles?: Record; getLanguageTitle?: (locale: string) => string; typePrefix?: string; // デフォルト: 'internationalizedArray' includeCompatibilityTypes?: boolean; // デフォルト: true components?: { input?: ComponentType | false; item?: ComponentType | false; field?: ComponentType | false; }; }; type FieldLevelFieldType = | 'string' | 'text' | 'block' | { name: string; type: string; title?: string; of?: unknown[]; fields?: unknown[]; options?: Record; }; ``` 組み込みの `fieldTypes` ショートカットは `string`、`text`、`block` (Portable Text) です。オブジェクトのエントリでは、カスタム生成型を定義します。`getLanguageTitle` と `languageTitles` の両方が設定されている場合は、`getLanguageTitle` が `languageTitles` より優先されます。各 `components` スロットには、Studio コンポーネント、または Sanity's のデフォルトレンダリングを使用するための `false` を指定できます。 ### `fieldLevelLocalization` [#field-level-localization] **Type** `GTFieldLevelLocalizationConfig` · **任意** [`internationalizedArray`](#internationalized-array) の説明用エイリアス。 ### `translationLevel` [#translation-level] **型** `'document' | 'internationalizedArray' | 'mixed'` · **任意** · **デフォルト** `'document'` 一致したドキュメントの翻訳方法を制御します。 * `'document'` はロケールごとに 1 つのドキュメントを作成します * `'internationalizedArray'` は設定されたフィールドをインプレースでローカライズします * `'mixed'` は [`fieldLevelDocuments`](#field-level-documents) にはフィールドレベルのローカライゼーションを使用し、それ以外にはドキュメントレベルのローカライゼーションを使用します ### `fieldLevelDocuments` [#field-level-documents] **Type** `TranslateDocumentFilter[] | string[]` · **任意** · **デフォルト** `[]` `translationLevel` が `'mixed'` の場合に、国際化配列を使用するドキュメント型を指定します。[`translateDocuments`](#translate-documents) と同じフィルター形式、および省略記法としての文字列形式を受け付けます。 ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }], internationalizedArray: { enabled: true, fieldTypes: ['string', 'text', 'block'], languageTitles: { es: 'Español', fr: 'Français' }, }, translationLevel: 'mixed', fieldLevelDocuments: [{ type: 'siteSettings' }], }); ``` 次に、生成された型をスキーマ内で使用します: ```ts defineField({ name: 'title', type: 'internationalizedArrayString', }); ``` ## フィールドマッチャー [#field-matchers] `ignoreFields`、`dedupeFields`、`skipFields` はそれぞれ、`FieldMatcher` オブジェクトの配列を受け取ります。マッチャーは JSONPath の `property` 式で対象のフィールドを指定し、必要に応じて `documentId` で 1 つのソースドキュメントに限定できます。 ```ts type FieldMatcher = { documentId?: string | null; // _id でソースドキュメントを絞り込む fields?: { property: string; // JSONPath 式（例: $.slug） type?: string; // 省略可能なスキーマ型のヒント（例: slug） }[]; }; ``` ### `ignoreFields` [#ignore-fields] **型** `FieldMatcher[]` · **任意** · **デフォルト** `[]` translation API に送信せず、source document から translated document にそのままコピーするフィールドです。カテゴリやタグのように、ロケールが異なっても同一のままにしておく値に使用します。 ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], ignoreFields: [ // すべてのドキュメントに対してカテゴリをそのままコピー { fields: [{ property: '$.category' }] }, // 特定のドキュメントのみタグをそのままコピー { documentId: 'homepage', fields: [{ property: '$.tags' }] }, ], }); ``` ### `dedupeFields` [#dedupe-fields] **Type** `FieldMatcher[]` · **任意** · **デフォルト** `[]` 翻訳済みドキュメントの初回作成時に、ソース値からコピーされ、末尾にロケールを追加して一意になるようにするフィールドです。主にスラッグに使用されます。 ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], // "about" は "about-es" と "about-fr" になります dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }], }); ``` スラッグフィールドでは、プラグインがスラッグオブジェクトの `current` の値を更新します。後でエディターが翻訳済みのスラッグを変更した場合、以降のインポートではその変更後の値が保持されます。 ### `skipFields` [#skip-fields] **型** `FieldMatcher[]` · **任意** · **デフォルト** `[]` 翻訳済みドキュメントから完全に削除されるフィールドです。 ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], skipFields: [ { fields: [{ property: '$.slug', type: 'slug' }] }, { documentId: 'homepage', fields: [{ property: '$.debugInfo' }] }, ], }); ``` ## シリアライズ [#serialization] このプラグインは、翻訳用にドキュメントをHTMLへシリアライズし、翻訳結果をSanityのフィールドにデシリアライズして戻します。ほとんどのプロジェクトでは、これらのオプションは必要ありません。 ### `additionalStopTypes` [#additional-stop-types] **型** `string[]` · **任意** · **デフォルト** `[]` 翻訳せずに保持する追加の schema タイプです。[デフォルトの stop types](#stop-types) に追加されます。 ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], additionalStopTypes: ['codeBlock', 'mux.video', 'mux.videoAsset'], }); ``` ### `additionalSerializers` [#additional-serializers] **型** `Partial` · **任意** · **デフォルト** `{}` デフォルトのシリアライザーにマージされるカスタムシリアライザーです。`@portabletext/to-html` のコンポーネント構造 (`types`、`marks`、`block`、`list`、`listItem` など) に従います。主にカスタム `marks` のシリアライズに使用します。 カスタム `marks` では、マークのデータが翻訳後も保持されるよう、出力を `attachGTData` でラップしてください。 ```ts title="sanity.config.ts" import { attachGTData, gtPlugin } from 'gt-sanity'; gtPlugin({ sourceLocale: 'en', locales: ['es'], additionalSerializers: { marks: { link: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), inlineMath: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), }, }, }); ``` `attachGTData(html, data, 'markDef')` は、`html` の最初の要素の `data-gt-internal` 属性に `data` をbase64エンコードして埋め込み、更新済みの HTML を返します。インポート時には、プラグインがその属性を読み取って mark 定義を再構築します。 ```ts function attachGTData( html: string, data: Record, type: 'markDef' ): string; ``` ### `additionalDeserializers` [#additional-deserializers] **Type** `CustomDeserializers` · **任意** · **デフォルト** `{}` 翻訳済みのHTML要素をSanityオブジェクトに戻すカスタムデシリアライザーです。typeごとにキーで指定します。 ```ts type CustomDeserializers = { types?: Record< string, (element: HTMLElement) => Record | unknown[] >; } & Record; ``` ### `additionalBlockDeserializers` [#additional-block-deserializers] **Type** `unknown[]` · **任意** · **デフォルト** `[]` Portable Text ブロック用の追加のデシリアライザールールです。プラグインの組み込みルールの末尾に追加されます。各ルールは `deserialize(node, next)` メソッドを持つオブジェクトで、`@portabletext/block-tools` のルール形式に準拠します。 ## デフォルトの stop types [#stop-types] これらのスキーマ型はそのまま保持され、翻訳対象として送信されることはありません。さらに追加するには [`additionalStopTypes`](#additional-stop-types) を使用します。 ```ts const defaultStopTypes = [ 'reference', 'date', 'datetime', 'file', 'geopoint', 'image', 'number', 'crop', 'hotspot', 'boolean', 'url', 'color', 'code', ]; ``` スラッグフィールドはデフォルトでは*スキップされない*ため、[`dedupeFields`](#dedupe-fields) または [`skipFields`](#skip-fields) を使わない限り、スラッグの `current` 文字列は翻訳されます。 ## エクスポートされるヘルパー [#helpers] `gt-sanity` は、高度なシリアライズやカスタムドキュメントノード向けの構成要素もエクスポートしています。ほとんどのプロジェクトでは必要ありません。 * `TranslationsTab` — `structureTool` 用のドキュメントタブコンポーネントです。[Sanity の設定](/docs/integrations/sanity/guides/configuring-sanity#translations-tab)を参照してください。 * `attachGTData` / `detachGTData` — カスタムシリアライザーで使われるエンコード済みのマークデータを付与および読み取ります。 * `BaseDocumentSerializer`, `BaseDocumentDeserializer`, `BaseDocumentMerger` — デフォルトのシリアライズ、デシリアライズ、マージの実装です。 * `defaultStopTypes`, `customSerializers` — デフォルトの stop types とシリアライザーのセットです。 * `documentInternationalization` とその型 (`DocumentInternationalizationConfig`, `Language`, `Metadata`, `TranslationReference`) — `@sanity/document-internationalization` から再エクスポートされています。 ## 完全な例 [#complete-example] ```ts 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', translateDocuments: [{ type: 'article' }, { type: 'page' }], singletons: ['siteSettings', 'navigation'], singletonMapping: (id, locale) => `${id}_${locale}`, // フィールドの動作 ignoreFields: [{ fields: [{ property: '$.category' }] }], dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }], skipFields: [{ fields: [{ property: '$.internalNotes' }] }], // シリアライゼーション — デフォルトがスキーマに対応していない場合のみ additionalSerializers: { marks: { link: ({ value, children }) => attachGTData(`${children}`, value, 'markDef'), }, }, }), ], }); ```