# General Translation Integrations: Конфигурация плагина Sanity URL: https://generaltranslation.com/ru/docs/integrations/sanity/reference/plugin-configuration.mdx Docs index: https://generaltranslation.com/llms.txt Description: Настройте плагин gt-sanity от General Translation для Sanity Studio. Справочник по API для gtPlugin. Зарегистрируйте General Translation в конфигурации Sanity с помощью функции `gtPlugin`. Передайте один объект параметров. ```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) | Алиас для `sourceLocale` при использовании spread с `gt.config.json`. | `string` | Да | — | | [`locales`](#locales) | Коды целевых локалей. Записи исходной локали и дубликаты удаляются. | `string[]` | Нет | — | | [`customMapping`](#custom-mapping) | Пользовательские сопоставления кодов локалей и переопределения свойств. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Да | — | | [`apiKey`](#api-key) | API-ключ General Translation. | `string` | Да | Документ Secrets | | [`projectId`](#project-id) | ID проекта General Translation. | `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) | Типы документов, использующие локализацию на уровне полей в смешанном режиме. | `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) | Поля, которые копируются из source без перевода. | `FieldMatcher[]` | Да | `[]` | | [`dedupeFields`](#dedupe-fields) | Поля, которые копируются из source и становятся уникальными для каждой локали. | `FieldMatcher[]` | Да | `[]` | | [`skipFields`](#skip-fields) | Поля, удаляемые из переведённых документов. | `FieldMatcher[]` | Да | `[]` | | [`additionalStopTypes`](#additional-stop-types) | Дополнительные типы схемы, которые сохраняются без перевода. | `string[]` | Да | `[]` | | [`additionalSerializers`](#additional-serializers) | Пользовательские HTML-сериализаторы для `marks` и типов блоков. | `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` в плагин через spread. Если заданы оба параметра, приоритет у `sourceLocale`. ```ts import gtConfig from './gt.config.json'; gtPlugin({ ...gtConfig }); ``` ### `locales` [#locales] **Type** `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 Ваш API-ключ General Translation. Если задан, передаётся в библиотеку при запуске. Если есть документ secrets, во время выполнения приоритет имеет его поле `secret`. Рекомендуется использовать документ secrets, чтобы ключи не попадали в систему контроля версий. ### `projectId` [#project-id] **Тип** `string` · **Необязательно** · **По умолчанию** считывается из документа secrets ID вашего проекта General Translation. Если документ secrets присутствует, в Runtime приоритет имеет его поле `project`. ### `secretsNamespace` [#secrets-namespace] **Тип** `string` · **Необязательно** · **По умолчанию** `generaltranslation.secrets` `_id` приватного документа Sanity, в котором хранятся учетные данные. Плагин получает этот документ по `_id` и использует его поле `secret` как API-ключ, а поле `project` — как 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] **Тип** `string` · **Необязательно** · **По умолчанию** `language` Поле документа, используемое для хранения локали каждого перевода на уровне документа. Добавьте поле с этим именем в типы документов, переводимых с использованием локализации на уровне документа, и используйте его в запросах, чтобы получать конкретную локаль. Локализация на уровне полей не использует это поле. ### `translateDocuments` [#translate-documents] **Тип** `TranslateDocumentFilter[] | 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}` `` Сопоставляет ID исходного документа синглтона и локаль с 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` с языковыми бейджами, меню переводов и шаблонами документов для каждого языка. В качестве типов схемы он использует элементы `type` в [`translateDocuments`](#translate-documents), а в качестве поддерживаемых языков — исходную локаль, за которой следуют нормализованные целевые локали, поэтому этот параметр действует только тогда, когда `translateDocuments` включает типы документов. Типы документов, локализованные на месте с помощью интернационализированных массивов, исключаются автоматически. Установите `false`, чтобы управлять интернационализацией самостоятельно. Если вы уже регистрируете `@sanity/document-internationalization` в своём Studio, сохраните текущую конфигурацию и установите для этого параметра значение `false`, чтобы плагин (и его тип документа `translation.metadata`) регистрировался только один раз — двойная регистрация вызывает ошибку дублирования типа схемы. Перевод будет работать с вашим экземпляром без изменений: плагин читает и записывает документы через [`languageField`](#language-field) и документы `translation.metadata` независимо от того, какая регистрация их добавила. Используйте одинаковые идентификаторы языков и одно и то же языковое поле в обеих конфигурациях. ## Локализация на уровне полей [#field-level] Локализация на уровне полей хранит значения всех локалей в одном документе в виде интернационализированного массива. Она реализована на базе [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array): `gtPlugin` настраивает нативный плагин, который регистрирует типы схемы `internationalizedArray*` и UI редактирования в Studio. Сохраняемые данные используют структуру элементов `{ _key, _type, language, value }`, поэтому для существующего контента internationalized-array миграция не требуется — и перевод работает одинаково независимо от того, зарегистрированы ли типы через `gtPlugin` или через вашу собственную регистрацию `internationalizedArray()`. **Изменено в v3:** локализация на уровне полей теперь предоставляется `sanity-plugin-internationalized-array` вместо типов и компонентов, генерируемых GT. `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) или объектную запись, определяющую пользовательское обёрнутое поле; объектная запись с именем `seo` регистрирует `internationalizedArraySeo`. `getLanguageTitle` переопределяет `languageTitles`, если заданы оба. `defaultLanguages` определяет, какие локали предварительно заполняются в пустых локализованных полях, и по умолчанию использует исходную локаль. `apiVersion`, `buttonLocations`, `buttonAddAll` и `languageDisplay` передаются в нативный плагин без изменений. ### `fieldLevelLocalization` [#field-level-localization] **Тип** `GTFieldLevelLocalizationConfig` · **Необязательно** Описательный алиас для [`internationalizedArray`](#internationalized-array). ### `translationLevel` [#translation-level] **Тип** `'document' | 'internationalizedArray' | 'mixed'` · **Необязательно** · **По умолчанию** `'document'` Определяет, как переводятся совпадающие документы: * `'document'` создает один документ для каждой локали * `'internationalizedArray'` локализует настроенные поля на месте * `'mixed'` использует локализацию на уровне полей для [`fieldLevelDocuments`](#field-level-documents) и локализацию на уровне документа для всего остального ### `fieldLevelDocuments` [#field-level-documents] **Тип** `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, плагин сохраняет все пять настроек в `localStorage`, привязывая их к проекту и набору данных Sanity. При последующих посещениях сохранённые значения имеют приоритет над конфигурацией плагина. Если хранилище браузера недоступно, изменение действует до перезагрузки Studio. ### `autoRefresh` [#auto-refresh] **Тип** `boolean` · **Необязательный** · **По умолчанию** `true` Задаёт начальное состояние **автообновления**. Если включено, диалог документа проверяет статус перевода каждые 10 секунд. Ручное **обновление** выполняет однократную проверку независимо от этого параметра. ### `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, }); ``` Редакторы могут изменить этот параметр в инструменте **Translations** или диалоговом окне документа. Как и для других настроек workflow, сохранённый ими выбор имеет приоритет над настроенным начальным значением при последующих посещениях. Когда переключатель включён, содержимое 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 или более поздней версии и объявляет диапазон peer-зависимости `sanity` как `^6.9.2`; пакеты Studio, которые он ранее включал, теперь являются peer-зависимостями. Studio на Sanity версий с 6.0 по 6.8 должны оставаться на `3.1.x`. | ## Вспомогательные функции структуры Studio [#structure-helpers] `gt-sanity` экспортирует две подключаемые вспомогательные функции для группировки переводов на уровне документа по локали в инструменте структуры Sanity's. | Вспомогательная функция | Описание | Возвращает | | ----------------------- | ----------------------------------------------------------------------------------------------- | ------------------- | | `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`. Типы, локализуемые на месте с помощью интернационализированных массивов, исключаются. Панель исходного языка содержит документы, у которых языковое поле отсутствует или соответствует `sourceLocale`; каждая панель целевой локали содержит документы, у которых языковое поле соответствует этой локали. * `types` переопределяет типы документов, выбранные в конфигурации плагина. * `sourceTitle` заменяет метку локали на панели исходного языка. * `localeTitle` получает заголовок типа схемы, код локали и отформатированную метку локали, а затем возвращает заголовок каждой панели целевой локали. Если не удаётся разрешить ни один тип документа, вспомогательная функция выводит предупреждение и не возвращает элементы списка. (Примеры конфигурации см. в разделе [Просмотр переводов по локали](/docs/integrations/sanity/guides/configuring-sanity#browse-locales)). ## Сопоставители полей [#field-matchers] `ignoreFields`, `dedupeFields` и `skipFields` принимают массив объектов `FieldMatcher`. Сопоставитель указывает поля с помощью выражения JSONPath `property` и при необходимости ограничивается одним исходным документом через `documentId`. Чтобы исключить поле везде, где оно встречается, лучше пометить его в схеме с помощью [параметров исключения в схеме](#schema-exclusion). ```ts type FieldMatcher = { documentId?: string | null; // ограничить до исходного документа по _id fields?: { property: string; // JSONPath-выражение, например $.slug type?: string; // необязательная подсказка типа схемы, например slug }[]; }; ``` ### `ignoreFields` [#ignore-fields] **Тип** `FieldMatcher[]` · **Необязательно** · **По умолчанию** `[]` Поля копируются из исходного документа в переведённый документ без отправки в API перевода. Используйте это для значений, которые должны оставаться одинаковыми во всех локалях, например для категорий или тегов. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], ignoreFields: [ // Копировать категорию без изменений для всех документов { fields: [{ property: '$.category' }] }, // Копировать теги без изменений только для одного документа { documentId: 'homepage', fields: [{ property: '$.tags' }] }, ], }); ``` ### `dedupeFields` [#dedupe-fields] **Тип** `FieldMatcher[]` · **Необязательно** · **По умолчанию** `[]` Поля, скопированные из исходного значения и делающиеся уникальными за счёт добавления локали при первом создании переведённого документа. Обычно используются для slug. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es', 'fr'], // "about" становится "about-es" и "about-fr" dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }], }); ``` Для поля slug плагин обновляет значение `current` в объекте slug. Если редактор позже изменит переведённый slug, при последующих импортах это изменённое значение сохранится. ### `skipFields` [#skip-fields] **Тип** `FieldMatcher[]` · **Необязательно** · **По умолчанию** `[]` Поля, полностью исключаемые из переведённых документов. ```ts gtPlugin({ sourceLocale: 'en', locales: ['es'], skipFields: [ { fields: [{ property: '$.slug', type: 'slug' }] }, { documentId: 'homepage', fields: [{ property: '$.debugInfo' }] }, ], }); ``` ## Параметры исключения в схеме [#schema-exclusion] Поля и типы можно исключать из перевода прямо в схеме, без записи в конфигурации плагина. Во время сериализации плагин проверяет `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 (интерфейс `GTSchemaFieldOptions`), поэтому `options.gt` проходит проверку типов в любом определении поля. *Примечание: исключение на уровне схемы помечает поле по имени и типу; для правил, нацеленных на конкретный документ по ID или преобразующих значения для каждой локали, используйте [`ignoreFields`, `skipFields`, and `dedupeFields`](#field-matchers).* ## Сериализация [#serialization] Плагин сериализует документы в HTML для перевода, а затем десериализует результат обратно в поля Sanity. Большинству проектов эти параметры не нужны. ### `additionalStopTypes` [#additional-stop-types] **Тип** `string[]` · **Необязательно** · **По умолчанию** `[]` Дополнительные типы схем, которые нужно сохранять без перевода в дополнение к [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`, чтобы данные `mark` сохранялись при переводе. ```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')` кодирует `data` в формат base64 и записывает его в атрибут `data-gt-internal` первого элемента `html`, а затем возвращает обновлённый HTML. При импорте плагин считывает этот атрибут, чтобы заново создать определение метки. ```ts function attachGTData( html: string, data: Record, type: 'markDef' ): string; ``` ### `additionalDeserializers` [#additional-deserializers] **Тип** `CustomDeserializers` · **Необязательно** · **По умолчанию** `{}` Пользовательские десериализаторы, которые преобразуют переведённые HTML-элементы обратно в объекты Sanity, сопоставляя их по типу. ```ts type CustomDeserializers = { types?: Record< string, (element: HTMLElement) => Record | unknown[] >; } & Record; ``` ### `additionalBlockDeserializers` [#additional-block-deserializers] **Тип** `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', ]; ``` Поля slug *по умолчанию не исключаются*, поэтому строковое значение `current` у slug переводится, если только вы не используете [`dedupeFields`](#dedupe-fields) или [`skipFields`](#skip-fields). ## Экспортируемые вспомогательные функции [#helpers] `gt-sanity` также экспортирует базовые компоненты для структуры Studio, расширенной сериализации и пользовательских узлов документа. Большинству проектов они не нужны. * `TranslationsTab` — компонент вкладки документа для `structureTool`. (См. [Настройка Sanity](/docs/integrations/sanity/guides/configuring-sanity#translations-tab)). * `gtStructure` / `gtStructureItems` и `GTStructureOptions` — вспомогательные функции структуры Studio с группировкой по локалям. (См. [Вспомогательные функции структуры Studio](#structure-helpers)). * `attachGTData` / `detachGTData` — прикрепляют и считывают закодированные данные mark, используемые пользовательскими сериализаторами. * `BaseDocumentSerializer`, `BaseDocumentDeserializer`, `BaseDocumentMerger` — стандартные реализации сериализации, десериализации и merge. * `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-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.