# sanity: Быстрый старт с Sanity
URL: https://generaltranslation.com/ru/docs/sanity/guides/quickstart.mdx
---
title: Быстрый старт с Sanity
description: Интегрируйте General Translation с Sanity CMS с помощью gt-sanity
---

**Предварительные требования:** Sanity Studio v5+, React 19+, существующий проект Sanity

<Callout type="warn">
  **Требуются изменения в схеме и на фронтенде.** Каждый тип документа, который вы переводите, должен включать поле `language` в своей схеме — подробности см. в разделе [настройка поля language](/docs/sanity#language-field).
  Переводы хранятся в виде отдельных документов, поэтому вам также потребуется обновить запросы на фронтенде, чтобы получать нужную языковую версию.
  Примеры см. ниже в разделе [Запрос переведённого контента](#querying-translated-content).
</Callout>

## Установка

Установите пакет `gt-sanity` в каталоге студии Sanity:

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-sanity
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-sanity
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-sanity
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-sanity
    ```
  </Tab>
</Tabs>

## Конфигурация

<Steps>
  <Step title="Добавьте плагин в конфигурацию Sanity">
    ```typescript title="sanity.config.ts"
    import { defineConfig } from 'sanity'
    import { gtPlugin } from 'gt-sanity'

    export default defineConfig({
      // ... ваша текущая конфигурация
      plugins: [
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja'], // Замените на целевые локали
          translateDocuments: [{ type: 'article' }, { type: 'page' }], // Типы документов, для которых нужно включить переводы
        })
      ]
    })
    ```

    Если указан `translateDocuments`, плагин автоматически добавляет возможности @sanity/document-internationalization: языковые бейджи, меню переводов в панели инструментов документа и шаблоны документов для каждого языка. Чтобы отключить это, задайте `showDocumentInternationalization: false`.
  </Step>

  <Step title="Добавьте поле language в свои схемы">
    Каждый тип документа, который вы переводите, должен иметь поле `language`:

    ```typescript title="schema/article.ts"
    import { defineField, defineType } from 'sanity'

    export const articleType = defineType({
      name: 'article',
      title: 'Article',
      type: 'document',
      fields: [
        // ... ваши существующие поля
        defineField({
          name: 'language',
          type: 'string',
          readOnly: true,
          hidden: true,
        }),
      ],
    })
    ```

    Если вы настроили пользовательское `languageField` в параметрах плагина, используйте это имя вместо `'language'`.
  </Step>

  <Step title="Настройте учетные данные API">
    В папке Studio создайте файл `populateSecrets.js` со следующим содержимым:

    ```javascript title="populateSecrets.js"
    import { getCliClient } from 'sanity/cli';

    const client = getCliClient({ apiVersion: '2026-04-06' });

    client.createOrReplace({
      // `.` в этом _id гарантирует, что документ будет приватным
      // даже в публичном датасете!
      _id: 'generaltranslation.secrets',
      _type: 'generaltranslationSettings',
      secret: process.env.GT_API_KEY,
      project: process.env.GT_PROJECT_ID,
    });
    ```

    Затем получите API-ключ для продакшена на [dash.generaltranslation.com](https://dash.generaltranslation.com).

    Запустите скрипт, подставив свои учетные данные:

    ```bash
    GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token
    ```

    Убедитесь, что документ был создан: откройте инструмент Vision в Studio и выполните запрос `*[_id == 'generaltranslation.secrets']`.

    Примечание: если у вас несколько датасетов, это нужно сделать для каждого из них.

    Если документ появился в вашем датасете или датасетах, удалите `populateSecrets.js`.

    <Callout type="warn">
      Эти учетные данные будут храниться в базе данных Sanity. По умолчанию они сохраняются в документе `generaltranslation.secrets`, который по умолчанию является приватным даже в публичном датасете.
      Однако, если вас беспокоит, что они могут быть доступны аутентифицированным пользователям Studio, вы можете ограничить доступ к этому пути с помощью [ролевого управления доступом](https://www.sanity.io/docs/access-control).
    </Callout>
  </Step>

  <Step title="(Необязательно) Добавьте отдельную вкладку Translations">
    Плагин автоматически добавляет действие **Translate** в каждый документ — оно открывает диалоговое окно. Если вам также нужна отдельная вкладка, добавьте компонент `TranslationsTab` в представления документа:

    ```typescript title="sanity.config.ts"
    import { defineConfig } from 'sanity'
    import { structureTool } from 'sanity/structure'
    import { gtPlugin, TranslationsTab } from 'gt-sanity'

    export default defineConfig({
      // ... ваша конфигурация
      plugins: [
        structureTool({
          structure: (S) =>
            S.list()
              .title('Content')
              .items(S.documentTypeListItems()),
          defaultDocumentNode: (S, { schemaType }) => {
            return S.document().views([
              S.view.form(),
              S.view
                .component(TranslationsTab)
                .title('General Translation')
            ])
          }
        }),
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja']
        })
      ]
    })
    ```
  </Step>
</Steps>

## Использование

После настройки вы сможете переводить документы напрямую из Sanity Studio:

1. Откройте любой документ в Studio
2. Нажмите кнопку **Translate** на панели действий документа — откроется диалоговое окно
3. Выберите целевые языки
4. Нажмите **Generate Translations**, чтобы отправить контент на перевод
5. По умолчанию плагин автоматически импортирует переводы обратно в документ, как только они будут готовы.
6. Кроме того, импортированные документы будут автоматически проверяться на наличие ссылок на другие документы, а затем в них будут автоматически обновляться ссылки, чтобы они указывали на правильные переводы этих документов.

## Запрос переведённого контента

Плагин хранит переводы в виде отдельных документов с полем `language` (настраивается через [`languageField`](/docs/sanity/api/plugin-config)). Ваши существующие GROQ-запросы к исходному контенту продолжат работать без изменений.

Чтобы получить переведённый контент, добавьте фильтрацию по полю `language`:

<Tabs items={["Базовый запрос", "Локализованный запрос"]}>
  <Tab value="Base Query">
    Ваши существующие запросы остаются прежними — ничего менять не нужно:

    ```plaintext
    // Получить все статьи (возвращает документы на исходном языке)
    *[_type == "article"]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Localized Query">
    Чтобы получить переведённые документы, добавьте фильтр по `language`:

    ```plaintext
    // Получить статьи на испанском языке
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }

    // Получить конкретную статью на определённом языке
    *[_type == "article" && slug.current == "hello-world" && language == "es"][0]{
      title,
      body
    }

    // Получить статьи на любом языке
    *[_type == "article"]{
      title,
      slug,
      body,
      language
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  У исходных документов по умолчанию поле `language` не задано. Чтобы запрашивать исходный контент вместе с переводами, можно отфильтровать документы, у которых `language` либо равно исходной локали, либо не задано: `language == "en" || !defined(language)`.
</Callout>

## Что дальше

* [Руководство по настройке](/docs/sanity/guides/configuration) - Настройка поведения плагина
* [Руководство по сериализации](/docs/sanity/guides/serialization) - Пользовательские правила сериализации
* [Справочник API](/docs/sanity/api/plugin-config) - Полный список параметров конфигурации