# General Translation Integrations: Sanity プラグインの設定 URL: https://generaltranslation.com/ja/docs/integrations/sanity/reference/plugin-configuration.mdx Docs index: https://generaltranslation.com/llms.txt Description: Sanity Studio 向けの General Translation `gt-sanity` プラグインを設定します。`gtPlugin` の API リファレンス。 `gtPlugin` 関数を使用して、Sanity config に 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) | フィールドレベルのローカライゼーション向けに `sanity-plugin-internationalized-array` を設定します。 | `GTFieldLevelLocalizationConfig` | はい | — | | [`fieldLevelLocalization`](#field-level-localization) | `internationalizedArray` の エイリアス。 | `GTFieldLevelLocalizationConfig` | はい | — | | [`translationLevel`](#translation-level) | ドキュメント単位、フィールドレベル、または混在の翻訳を選択します。 | `'document' \| 'internationalizedArray' \| 'mixed'` | はい | `'document'` | | [`fieldLevelDocuments`](#field-level-documents) | mixed モードでフィールドレベルのローカライゼーションを使用するドキュメントタイプ。 | `TranslateDocumentFilter[] \| string[]` | はい | `[]` | | [`autoRefresh`](#auto-refresh) | 自動翻訳ステータス ポーリングの初期状態。 | `boolean` | はい | `true` | | [`autoImport`](#auto-import) | 翻訳完了時の自動インポートの初期状態。 | `boolean` | はい | `true` | | [`autoPatchReferences`](#auto-patch-references) | インポート後の参照のパッチ適用の初期状態。 | `boolean` | はい | `false` | | [`autoPublish`](#auto-publish) | インポート後の公開の初期状態。 | `boolean` | はい | `false` | | [`preserveExistingTranslations`](#preserve-existing-translations) | **ローカル編集を保存** トグルの初期状態。 | `boolean` | はい | `false` | | [`ignoreFields`](#ignore-fields) | 翻訳せずにソースからコピーするフィールド。 | `FieldMatcher[]` | はい | `[]` | | [`dedupeFields`](#dedupe-fields) | ソースからコピーし、ロケールごとに一意化するフィールド。 | `FieldMatcher[]` | はい | `[]` | | [`skipFields`](#skip-fields) | 翻訳済みドキュメントから削除するフィールド。 | `FieldMatcher[]` | はい | `[]` | | [`additionalStopTypes`](#additional-stop-types) | 翻訳せずに保持する追加の スキーマ型。 | `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']` などです。プラグインは、翻訳または Sanity のローカライゼーションプラグインを設定する前に、重複するエントリと、解決されたソースロケールと同じエントリを削除します。 | バージョン | 変更内容 | | ------- | ---------------------------------------------------------------------- | | `3.1.1` | 翻訳および Sanity のローカライゼーションプラグインを設定する前に、重複する対象ロケールと解決されたソースロケールを削除します。 | ### `customMapping` [#custom-mapping] **型** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **任意** ロケールコードから名前へのカスタムマッピング、またはロケールのプロパティを上書きする設定です。`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` エントリを スキーマ型 とし、ソースロケールと、それに続く正規化されたターゲットロケールをサポート対象の言語として使用するため、`translateDocuments` にドキュメントタイプが含まれている場合にのみ機能します。国際化配列を使ってインプレースでローカライズされたドキュメントタイプは、自動的に除外されます。国際化を自分で管理する場合は、`false` に設定してください。 すでに Studio で `@sanity/document-internationalization` を登録している場合は、その設定をそのまま使い、このオプションを `false` に設定してください。これにより、プラグイン (およびその `translation.metadata` ドキュメントタイプ) は 1 回だけ登録されます。2 回登録すると、スキーマ型 の重複エラーが発生します。どの登録によって追加されたかに関係なく、このプラグインは [`languageField`](#language-field) と `translation.metadata` ドキュメントを通じてドキュメントを読み書きするため、翻訳は既存のインスタンスでもそのまま機能します。両方の設定で同じ言語 ID と language フィールドを使用してください。 ## フィールドレベルのローカライゼーション [#field-level] フィールドレベルのローカライゼーションでは、各ロケールの値を 1 つのドキュメント内の国際化配列として保存します。これは [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array) によって実現されます。`gtPlugin` はこのネイティブのプラグインを設定し、`internationalizedArray*` スキーマ型と Studio の編集 UI を登録します。保存されるデータは `{ _key, _type, language, value }` というアイテム形状を使用するため、既存の internationalized-array コンテンツを移行する必要はありません。また、型が `gtPlugin` によって登録されていても、独自の `internationalizedArray()` 登録によって登録されていても、翻訳の動作は同じです。 **v3 での変更:** フィールドレベルのローカライゼーションは、GT が生成する型やコンポーネントではなく、`sanity-plugin-internationalized-array` によって提供されるようになりました。`createInternationalizedArrayTypes`、`FieldLevelUIComponents`、および `typePrefix`、`includeCompatibilityTypes`、`components` オプションは削除されました。削除済みのオプションを渡すと警告が出力され、そのオプションは無視されます。 ### `internationalizedArray` [#internationalized-array] **型** `GTFieldLevelLocalizationConfig` · **任意** フィールドレベルのローカライゼーション用に `sanity-plugin-internationalized-array` を設定します。ロケールの識別情報は常に `sourceLocale` と `locales` から取得されます。ネイティブのプラグインを自分で登録する場合は、このオプションは設定しないでください。そうすることで、スキーマ型は一度だけ登録されます。 ```ts type GTFieldLevelLocalizationConfig = { enabled?: boolean; // デフォルト: false fieldTypes?: FieldLevelFieldType[]; // デフォルト: ['string', 'text'] languageTitles?: Record; getLanguageTitle?: (locale: string) => string; defaultLanguages?: string[]; // デフォルト: [sourceLocale] // sanity-plugin-internationalized-array にそのまま渡される apiVersion?: string; buttonLocations?: ('field' | 'unstable__fieldAction' | 'document')[]; buttonAddAll?: boolean; languageDisplay?: 'titleOnly' | 'codeOnly' | 'titleAndCode'; }; type FieldLevelFieldType = | string | { name: string; type: string; title?: string; of?: unknown[]; fields?: unknown[]; options?: Record; }; ``` `fieldTypes` のエントリには、Sanity の型名 (`'string'`、`'text'`) 、`'block'` ショートカット (Portable Text の array) 、またはカスタムでラップされたフィールドを定義する object エントリを指定できます。`seo` という名前の object エントリを指定すると、`internationalizedArraySeo` が登録されます。両方が設定されている場合は、`getLanguageTitle` が `languageTitles` より優先されます。`defaultLanguages` は、空のローカライズ済みフィールドにどのロケールを事前入力するかを制御し、デフォルトではソースロケールが使用されます。`apiVersion`、`buttonLocations`、`buttonAddAll`、`languageDisplay` は、変更されずにネイティブのプラグインへそのまま渡されます。 ### `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'` の場合に、国際化配列を使用するドキュメント型を指定します。各エントリには、`{ type: 'siteSettings' }` のような型フィルター、または省略記法の文字列 `'siteSettings'` を指定できます。ドキュメント ID フィルターはここではサポートされていません。 ```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', }); ``` ## 翻訳ワークフローのオプション [#workflow-options] これらのオプションは、各スイッチの初期値を設定します。エディターがStudioでスイッチを変更すると、プラグインはSanityのプロジェクトとデータセットをキーとして、5つすべての設定を`localStorage`に保存します。保存された値は、次回以降のアクセス時にプラグイン設定よりも優先されます。ブラウザーストレージを利用できない場合、変更はStudioが再読み込みされるまで有効です。 ### `autoRefresh` [#auto-refresh] **型** `boolean` · **任意** · **デフォルト** `true` **自動更新**の初期状態を設定します。有効にすると、ドキュメントダイアログは10秒ごとに翻訳ステータスを確認します。この設定にかかわらず、手動で**更新**すると1回だけ確認します。 ### `autoImport` [#auto-import] **型** `boolean` · **任意** · **デフォルト** `true` **完了時に自動インポート**の初期状態を設定します。有効にすると、ドキュメントダイアログが開いている間に完了した翻訳がインポートされます。ダイアログを開いた時点ですでに完了していた翻訳は自動的に再インポートされないため、既存のSanityでの編集が上書きされることはありません。新しい翻訳実行を開始すると、この基準がリセットされます。 ### `autoPatchReferences` [#auto-patch-references] **型** `boolean` · **任意** · **デフォルト** `false` ドキュメント単位の翻訳で、**インポート後に自動パッチ**を適用するかどうかの初期状態を設定します。有効にすると、インポートしたドキュメントの参照先が同じロケールの翻訳済みドキュメントに変更されます。翻訳済みドキュメントがすでに公開されており、ドラフトがない場合、プラグインは公開済みの状態からドラフトを作成し、公開済みコンテンツを変更するのではなく、そのドラフトにパッチを適用します。 ### `autoPublish` [#auto-publish] **型** `boolean` · **任意** · **デフォルト** `false` ドキュメント単位の翻訳における**インポート後に自動公開**の初期状態を設定します。インポートでは常にドラフトが作成または更新されます。このオプションを有効にすると、ソースドキュメントの公開時に、インポートされた各翻訳が自動的に公開されます。 ### `preserveExistingTranslations` [#preserve-existing-translations] **型** `boolean` · **任意** · **デフォルト** `false` **ローカル編集を保存**トグルの初期状態を設定します。トグルをオンにすると、Sanity 内の既存の翻訳が翻訳実行前に General Translation に送信されます。これにより、ソーステキストが変更されていないコンテンツは再翻訳されず、既存の文言が保持されます。 ```ts title="sanity.config.ts" gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], translateDocuments: [{ type: 'post' }], preserveExistingTranslations: true, }); ``` Editor は **翻訳** ツールまたはドキュメントダイアログから、この設定を変更できます。他のワークフロー設定と同様に、保存された選択は以後のアクセス時に設定済みの初期値より優先されます。 トグルをオンにすると、Sanity の内容で、そのバージョンのドキュメントについて General Translation が保持している内容が置き換えられます。これには、完了しているもののまだインポートされていない翻訳も含まれます。有効にする前に、保留中の翻訳をすべてインポートしてください。 ([翻訳の編集を保持する](/docs/integrations/sanity/guides/translating-content#preserve-edits)を参照してください) 。 ### バージョン履歴 | バージョン | 変更内容 | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `3.1.0` | **ローカル編集を保存**トグル、その`preserveExistingTranslations`オプション、**ローカル編集を保存**アクション、**最初から再翻訳**を追加しました。 | | `3.1.4` | `autoRefresh`、`autoImport`、`autoPatchReferences`、`autoPublish`をプラグインオプションとして追加し、プロジェクトごと・データセットごとに保存されるようにしました。`autoPatchReferences`と`autoPublish`のデフォルトを`false`に変更しました。`autoRefresh`と`autoImport`は引き続き`true`です。 | | `3.1.6` | ドキュメント単位のインポートでは、公開済みドキュメントをパッチする代わりに公開状態から下書きを作成するようになったため、インポートによって自動公開設定が回避されなくなりました。 | | `4.0.0` | Sanity 6のサポートを追加し、Sanity 5世代のサポートを終了しました。パッケージはESM専用で、Node.js 22.12以降が必要です。また、`sanity`のピア依存関係のバージョン範囲として`^6.9.2`を宣言しています。以前バンドルされていたStudioパッケージは、現在はピア依存関係です。Sanity 6.0から6.8を使用するStudioは、`3.1.x`を継続して使用してください。 | ## Studio 構造ヘルパー [#structure-helpers] `gt-sanity` は、Sanity の構造ツールでドキュメント単位の翻訳をロケールごとにグループ化するための、2 つのオプトインヘルパーをエクスポートします。 | ヘルパー | 説明 | 戻り値 | | ------------------ | --------------------------------------------- | ------------------- | | `gtStructureItems` | カスタム構造に組み込むロケールごとのリスト項目を作成します。 | `ListItemBuilder[]` | | `gtStructure` | ロケールごとにグループ化された項目を含む完全な **Content** 構造を作成します。 | `StructureResolver` | ```ts type GTStructureOptions = { types?: string[]; sourceTitle?: string; localeTitle?: (typeTitle: string, locale: string, label: string) => string; }; function gtStructureItems( S: StructureBuilder, context?: StructureResolverContext, options?: GTStructureOptions ): ListItemBuilder[]; function gtStructure(options?: GTStructureOptions): StructureResolver; ``` デフォルトでは、ヘルパーは `translateDocuments` のドキュメントタイプをグループ化します。国際化配列を使用してインプレースでローカライズされるタイプは除外されます。ソースペインには、language フィールドがないドキュメント、または `sourceLocale` と一致するドキュメントが表示されます。各ターゲットペインには、language フィールドがそのロケールと一致するドキュメントが表示されます。 * `types` は、プラグイン設定で選択されたドキュメントタイプを上書きします。 * `sourceTitle` は、ソースペインのロケールラベルを置き換えます。 * `localeTitle` は、スキーマ型のタイトル、ロケールコード、書式設定済みのロケールラベルを受け取り、各ターゲットペインのタイトルを返します。 解決可能なドキュメントタイプがない場合、ヘルパーは警告をログに記録し、リスト項目を返しません。 (設定例については、[ロケール別に翻訳を参照する](/docs/integrations/sanity/guides/configuring-sanity#browse-locales)を参照してください) 。 ## フィールドマッチャー [#field-matchers] `ignoreFields`、`dedupeFields`、`skipFields` はそれぞれ、`FieldMatcher` オブジェクトの配列を受け取ります。マッチャーは JSONPath の `property` 式で対象のフィールドを指定し、必要に応じて `documentId` で 1 つのソースドキュメントに限定できます。フィールドが出現するすべての箇所で除外する場合は、代わりに [schema exclusion options](#schema-exclusion) を使ってスキーマ側でマークする方法を優先してください。 ```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' }] }, ], }); ``` ## スキーマの除外オプション [#schema-exclusion] フィールドと型は、plugin-config のエントリがなくても、スキーマ内で直接翻訳対象から除外できます。シリアライズ時に、プラグインは各スキーマ定義の `options` にある次の名前空間を確認し、一致したものを翻訳用に送信するコンテンツから除外します。 | オプション | 提供元プラグイン | | ---------------------------------------------- | --------------------------------------- | | `options.gt.exclude` | `gt-sanity` | | `options.documentInternationalization.exclude` | `@sanity/document-internationalization` | | `options.aiAssist.exclude` | `@sanity/assist` | いずれも `boolean` を受け取り、明示的に `true` が設定されている場合にのみ除外されます。除外はネストの深さに関係なく適用されます。除外されたコンテンツは翻訳のために送信されないため、翻訳済みドキュメントでも元の値がそのまま保持されます。 ```ts defineField({ name: 'internalNotes', type: 'string', options: { gt: { exclude: true } }, }); ``` カスタム型定義の `options` に除外オプションを設定すると、その型のすべての出現箇所が除外されます。これは、ネイティブ プラグインの「field or type」セマンティクスと同じです。従来の `localize: false` フィールドプロパティも引き続き尊重されます。 `gt-sanity` は Sanity の schema オプション型 (`GTSchemaFieldOptions` インターフェース) を拡張しているため、どのフィールド定義でも `options.gt` の型チェックが行われます。 *注: schema の除外は、フィールドを名前と型でマークします。ID で特定のドキュメントを対象にするルールや、ロケールごとに値を変換するルールには、[`ignoreFields`, `skipFields`, and `dedupeFields`](#field-matchers) を使用してください。* ## シリアライズ [#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` は、Studio 構造、高度なシリアライズやカスタムドキュメントノード向けの構成要素もエクスポートしています。ほとんどのプロジェクトでは必要ありません。 * `TranslationsTab` — `structureTool` 用のドキュメントタブコンポーネントです。 ([Sanity の設定](/docs/integrations/sanity/guides/configuring-sanity#translations-tab)を参照してください) 。 * `gtStructure` / `gtStructureItems` と `GTStructureOptions` — ロケールごとにグループ化された Studio 構造ヘルパーです。 ([Studio 構造ヘルパー](#structure-helpers)を参照してください) 。 * `attachGTData` / `detachGTData` — カスタムシリアライザーで使われるエンコード済みのマークデータを付与および読み取ります。 * `BaseDocumentSerializer`, `BaseDocumentDeserializer`, `BaseDocumentMerger` — デフォルトのシリアライズ、デシリアライズ、マージの実装です。 * `defaultStopTypes`, `customSerializers` — デフォルトの stop types とシリアライザーのセットです。 * `documentInternationalization` とその型 (`DocumentInternationalizationConfig`, `Language`, `Metadata`, `TranslationReference`) — `@sanity/document-internationalization` から再エクスポートされています。 * `internationalizedArray`, `internationalizedArrayLanguageFilter`, `isInternationalizedArrayItemType`、および `InternationalizedArrayPluginConfig` と `InternationalizedArrayLanguage` 型 — `sanity-plugin-internationalized-array` から再エクスポートされています。 * `GTSchemaFieldOptions` — `options.gt` を支える schema オプションのインターフェースです。 ([スキーマの除外オプション](#schema-exclusion)を参照してください) 。 ## 完全な例 [#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'), }, }, }), ], }); ``` ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.