# General Translation Integrations: 快速入门
URL: https://generaltranslation.com/zh/docs/integrations/sanity/quickstart.mdx
---

title: 快速入门
description: 安装 gt-sanity，将 General Translation 插件添加到 Sanity Studio，并翻译你的第一份文档。
related:
  links:
    - /docs/integrations/sanity/guides/translating-content
    - /docs/integrations/sanity/guides/managing-translations
    - /docs/integrations/sanity/guides/querying-translations
    - /docs/integrations/sanity/guides/configuring-sanity

---

General Translation 的 `gt-sanity` 插件可让你直接在 Sanity Studio 中翻译 Sanity 文档。

该插件采用文档级本地化：每个译文都会存储为单独的 Sanity 文档，并带有语言字段，例如 `language: "es"`。译文通过由 `@sanity/document-internationalization` 管理的 `translation.metadata` 文档与源文档关联。

## 开始之前 [#before-start]

你需要准备：

* Sanity Studio 5.0.0 或更高版本。
* React 19.2.0 或更高版本。
* 一个现有的 Sanity 项目。
* 一个 General Translation [项目 ID](/docs/platform/dashboard/get-started) 和一个生产环境 [API 密钥](/docs/platform/dashboard/reference/api-keys)。

## 快速入门 [#quickstart]

### 1. 安装 `gt-sanity` [#install]

在 Sanity Studio 项目中安装该插件。

<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` 设为 `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,
    }),
  ],
});
```

如果你在 plugin 的选项中设置了自定义的 [`languageField`](/docs/integrations/sanity/reference/plugin-configuration#language-field)，请在 schema 中使用该名称，而不要使用 `language`。

### 4. 存储凭据 [#credentials]

该插件会从私有的 Sanity 文档中读取你的 General Translation API 密钥和项目 ID。请在 Studio 文件夹中创建一个临时的 `populateSecrets.js` 文件。

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

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

client.createOrReplace({
  // `_id` 开头的 `.` 可使该文档保持私有，
  // 即使在公开数据集中亦然。
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslation.secrets',
  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`。

### 5. 翻译文档 [#translate-document]

1. 在 Sanity Studio 中打开源语言的文档。
2. 在文档操作栏中点击 **Translate**。
3. 选择目标区域设置。
4. 点击 **Generate Translations**。

在文档对话框中，插件会轮询已完成的翻译并自动导入。导入后，它会更新文档引用并发布翻译后的文档，因为在此对话框中，自动导入、自动修补和自动发布默认都是开启的。

请参阅[翻译内容](/docs/integrations/sanity/guides/translating-content)和[管理翻译](/docs/integrations/sanity/guides/managing-translations)的完整指南。

### 6. 查询翻译后的内容 [#query-content]

译文会以带有 language 字段 的独立文档形式存储。要获取翻译后的内容，请根据 language 字段 进行筛选。

<Tabs items={['源语言查询', '本地化查询']}>
  <Tab value="Source query">
    ```text
    // 源语言文档默认不会设置 language 字段
    *[_type == "article" && !defined(language)]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Localized query">
    ```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