# sanity: Конфигурация плагина
URL: https://generaltranslation.com/ru/docs/sanity/api/plugin-config.mdx
---
title: Конфигурация плагина
description: Справочник API по параметрам конфигурации gtPlugin
---

## Обзор

Функция `gtPlugin` настраивает General Translation для вашей студии Sanity.

```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: 'API-ключ GT (необязательно при использовании документа с секретами)',
optional: true,
},
projectId: {
type: 'string',
description: 'ID проекта GT (необязательно при использовании документа с секретами)',
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 (по умолчанию), автоматически добавляет плагин @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, а копируются из исходного документа с добавлением целевой локали при первом создании переведённого документа. Используйте это для полей, которые должны изначально быть производными от исходного документа, но при этом быть уникальными для каждого переведённого документа, например для slug&#39;ов в 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' }],
    },
  ],
});
```

Для полей slug в Sanity plugin обновляет значение `current` объекта slug. Например, при создании испаноязычного документа `{ _type: 'slug', current: 'about' }` становится `{ _type: 'slug', current: 'about-es' }`. Если редактор позже изменит переведённый slug, последующие импорты переводов сохранят это изменённое значение.

## SkipFields

Поля, которые полностью удаляются из переведённых документов. В отличие от `ignoreFields`, эти поля вообще не будут появляться в переводах. Используйте это для полей вроде канонических URL для SEO, метаданных, существующих только в исходном документе, или slug&#39;ов, которые редакторы должны задавать вручную для каждого языка.

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

### Пример

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  skipFields: [
    // Редакторы будут задавать slug вручную для каждого языка
    {
      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({
      // Required
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja'],

      // Document handling
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      singletonMapping: (id, locale) => `${id}_${locale}`,

      // Filtering
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [{ fields: [{ property: '$.publishedAt' }] }],
      dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }],
      skipFields: [{ fields: [{ property: '$.internalNotes' }] }],

      // Serialization - Do not use this unless you know what you are doing!
      additionalSerializers: {
        // Additional serializers for marks (custom annotations)
        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) - Пользовательская сериализация