# General Translation Integrations: 快速入门
URL: https://generaltranslation.com/zh/docs/integrations/sanity/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 安装 gt-sanity，将 General Translation 插件添加到 Sanity Studio，并翻译你的第一份文档。

`gt-sanity` 插件可让你直接在 Sanity Studio 中翻译文档。它支持文档级和字段级本地化；本快速入门使用默认的文档级设置，即每个译文都是单独的文档，并带有 `language` 字段，以及一个由 `@sanity/document-internationalization` 管理的 `translation.metadata` 文档。

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

你需要准备：

* Sanity Studio 6.9.2 或更高版本。使用 Sanity 6.0 至 6.8 的 Studio 仍采用 `@sanity/ui` 第 3 代，应继续使用 `gt-sanity` 3.1.x。
* React 19.2.0 或更高版本。
* Node.js 22.12 或更高版本。
* 一个现有的 Sanity 项目。
* 一个 General Translation [项目 ID](/docs/platform/dashboard/get-started) 和一个生产环境 [API 密钥](/docs/platform/dashboard/reference/api-keys)。

## 快速入门 [#quickstart]

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

在 Sanity Studio 项目中安装该插件。`gt-sanity` 会将 Studio 中的 `@sanity/ui`、`@sanity/icons`、`@sanity/schema` 和 `@sanity/mutator` 作为对等依赖项解析，以确保依赖树中每个 Studio 运行时单例仅保留一个副本。Sanity 6.9.2+ 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-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: '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">
  `_id` 开头的 `.` 可使该文档不出现在未经身份验证的公开数据集查询中，但已通过身份验证的 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]

采用这种文档级设置后，译文会以带有语言字段的独立文档形式存储。要获取翻译后的内容，请根据语言字段进行筛选。

<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

## Sitemap

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