# sanity: Конфигурация
URL: https://generaltranslation.com/ru/docs/sanity/guides/configuration.mdx
---
title: Конфигурация
description: Настройка плагина gt-sanity для проекта 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'], // Целевые языки для перевода
});
```


### Использование `defaultLocale` из `gt.config.json`

Если у вас уже есть `gt.config.json` (например, если вы используете `gt-next` или `gt-react`), вы можете напрямую передать его в конфигурацию плагина через оператор расширения. Поле `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' }],
});
```


### Перевод отдельных документов

Укажите идентификаторы нужных документов:

```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'], // Список идентификаторов документов-синглтонов
  singletonMapping: (docId, locale) => `${docId}-${locale}`, // Необязательная функция для настройки идентификаторов переведённых документов-синглтонов
});
```

По умолчанию у переводов для документов-синглтонов будут случайно сгенерированные идентификаторы, если не задан `singletonMapping`.


## Исключение полей

Поля, которые не нужно переводить или отправлять в API GT, но которые всё равно должны копироваться из исходного документа в перевод. Игнорируемые поля удаляются перед сериализацией (то есть содержимое никогда не отправляется в API), а затем восстанавливаются из исходного документа после создания переведённого документа.

Используйте `ignoreFields` для таких полей, как категории, теги или внутренние метаданные, которые должны иметь одинаковые значения в исходном и переведённом документах, но не требуют перевода:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  ignoreFields: [
    { fields: [{ property: '$.category' }] },       // одна категория для всех языков
    { fields: [{ property: '$..linkType' }] },       // внутренние метаданные ссылок
    { fields: [{ property: '$..frequencies.default' }] },
  ],
});
```

`property` — это выражение [JSONPath](https://goessner.net/articles/JsonPath/), которое соответствует одному или нескольким полям в документах.
`type` — необязательный параметр для дополнительной фильтрации игнорируемых полей по определённым типам.


## Дедупликация полей

Поля, которые не нужно переводить или отправлять в API GT, но при этом нужно копировать из исходного документа и делать уникальными при первом создании переведённого документа. Поля, указанные в дедупликации, удаляются перед сериализацией, а затем восстанавливаются из исходного документа с добавлением целевой локали.

Используйте `dedupeFields` для slug в Sanity и других строковых идентификаторов, которые должны сохранять исходное значение, но при этом быть уникальными для каждого языка:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  dedupeFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] }, // "about" становится "about-es"
  ],
});
```

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

## Пропуск полей

Поля, которые вообще не должны автоматически копироваться в переводы. В отличие от `ignoreFields` (который сохраняет исходное значение в переводе), `skipFields` полностью удаляет совпадающие поля из переведённого документа.

Используйте `skipFields` для таких полей, как канонические URL для SEO, метаданные, относящиеся только к исходному документу, или slug, которые редакторы должны задавать вручную для каждого языка:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },  // редакторы задают слаги вручную для каждого языка
    { fields: [{ property: '$.canonicalUrl' }] },         // only relevant on source
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],              // source-only debug data
    },
  ],
});
```

## Параметры сериализации

Расширьте стандартное поведение сериализации:

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalSerializers: {
    // Дополнительные сериализаторы для marks (пользовательские аннотации)
    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) - Полный список параметров конфигурации