# General Translation Integrations: Быстрый старт
URL: https://generaltranslation.com/ru/docs/integrations/sanity/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Установите `gt-sanity`, добавьте плагин General Translation в Sanity Studio и переведите свой первый документ.

Плагин `gt-sanity` переводит документы прямо в Sanity Studio. Он поддерживает локализацию на уровне документов и на уровне полей; в этом руководстве быстрого старта по умолчанию используется настройка на уровне документа, при которой каждый перевод хранится как отдельный документ с полем `language` и документом `translation.metadata`, которым управляет `@sanity/document-internationalization`.

## Перед началом [#before-start]

Вам понадобится:

* Sanity Studio 6.9.2 или новее. Студии на Sanity версий с 6.0 по 6.8 по-прежнему используют третье поколение `@sanity/ui` и должны оставаться на `gt-sanity` 3.1.x.
* React 19.2.0 или новее.
* Node.js 22.12 или новее.
* Существующий проект Sanity.
* [ID проекта](/docs/platform/dashboard/get-started) в General Translation и [API-ключ для production](/docs/platform/dashboard/reference/api-keys).

## Быстрый старт [#quickstart]

### 1. Установите `gt-sanity` [#install]

Установите плагин в проект Sanity Studio. `gt-sanity` использует `@sanity/ui`, `@sanity/icons`, `@sanity/schema` и `@sanity/mutator` из вашей Studio в качестве peer dependencies, поэтому в дереве сохраняется по одному экземпляру каждого синглтона среды выполнения Studio. Studio Sanity версии 6.9.2+ уже включает все четыре.

<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>

### 2. Добавьте плагин [#add-plugin]

Добавьте `gtPlugin` в `sanity.config.ts`. Укажите исходную локаль, целевые локали и типы документов, которые нужно переводить.

```ts 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`.

### 3. Добавьте поле `language` [#language-field]

Для каждого типа документа, который вы переводите с локализацией на уровне документа, нужно поле `language`. По умолчанию оно называется `language`.

```ts 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`](/docs/integrations/sanity/reference/plugin-configuration#language-field), используйте это имя в схеме вместо `language`.

### 4. Сохраните учетные данные [#credentials]

Плагин считывает ваш API-ключ General Translation и ID проекта из закрытого документа Sanity. Создайте временный файл `populateSecrets.js` в папке Studio.

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

const client = getCliClient({ apiVersion: '2025-09-15' });

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

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

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

Документ `_id` должен совпадать с `secretsNamespace` плагина (по умолчанию — `generaltranslation.secrets`). Плагин использует поле `secret` как API-ключ, а поле `project` — как ID проекта.

Убедитесь в Studio с помощью инструмента Vision, что документ существует:

```text
*[_id == 'generaltranslation.secrets']
```

Если вы используете несколько наборов данных, повторите это действие для каждого из них. После проверки удалите `populateSecrets.js`.

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

### 5. Переведите документ [#translate-document]

1. Откройте документ на исходном языке в Sanity Studio.
2. Нажмите **Translate** на панели действий документа.
3. Выберите целевые локали.
4. Нажмите **Translate**.

При такой настройке на уровне документа плагин отслеживает завершённые переводы и автоматически импортирует их как черновики. Обновление ссылок и публикация по умолчанию отключены; используйте элементы управления в диалоговом окне или настройте их начальное состояние с помощью [`autoPatchReferences`](/docs/integrations/sanity/reference/plugin-configuration#auto-patch-references) и [`autoPublish`](/docs/integrations/sanity/reference/plugin-configuration#auto-publish).

Проверьте импортированные документы в представлении Sanity **Drafts**, затем опубликуйте их перед выполнением запросов из фронтенда, работающего только с опубликованными документами.

(См. подробные руководства по [переводу контента](/docs/integrations/sanity/guides/translating-content) и [управлению переводами](/docs/integrations/sanity/guides/managing-translations)).

### 6. Запрос переведённого контента [#query-content]

При такой настройке на уровне документа переводы хранятся в виде отдельных документов с полем language. Чтобы получить переведённый контент, фильтруйте по полю language.

<Tabs items={['Исходный запрос', 'Локализованный запрос']}>
  <Tab value="Исходный запрос">
    ```text
    // В документах на исходном языке поле language по умолчанию не задано
    *[_type == "article" && !defined(language)]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Локализованный запрос">
    ```text
    // Получить статьи на испанском языке
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }
    ```
  </Tab>
</Tabs>

(См. раздел [Запросы к переводам](/docs/integrations/sanity/guides/querying-translations), чтобы узнать о других шаблонах запросов).

## Next steps

- /docs/integrations/sanity/guides/translating-content
- /docs/integrations/sanity/guides/managing-translations
- /docs/integrations/sanity/guides/querying-translations
- /docs/integrations/sanity/guides/configuring-sanity

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.