# sanity: Sanity 快速入门
URL: https://generaltranslation.com/zh/docs/sanity/guides/quickstart.mdx
---
title: Sanity 快速入门
description: 使用 gt-sanity 将 General Translation 集成到 Sanity CMS
---

**前提条件：** Sanity Studio v5+、React 19+、现有的 Sanity 项目

<Callout type="warn">
  **需要修改 schema 和前端。** 您要翻译的每种文档类型都必须在其 schema 中包含一个 `language` 字段——详见 [language 字段设置](/docs/sanity#language-field)。
  翻译内容会作为独立文档存储，因此您还需要更新前端查询，以获取正确的语言版本。
  示例请参见下方的[查询翻译内容](#querying-translated-content)。
</Callout>

## 安装

在 Sanity Studio 目录中安装 `gt-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 的相关功能：语言徽章、文档工具栏中的翻译菜单，以及各语言的文档 template。将 `showDocumentInternationalization: false` 设为禁用此功能。
  </Step>

  <Step title="向你的 schema 添加语言字段">
    你要翻译的每种文档类型都必须有一个 `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,
    });
    ```

    接下来，在 [dash.generaltranslation.com](https://dash.generaltranslation.com) 获取生产环境 API 密钥。

    使用你的凭据运行该脚本：

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

    在 Studio 中使用 Vision Tool 验证文档是否已创建，并查询 `*[_id == 'generaltranslation.secrets']`。

    注意：如果你有多个数据集，则需要在每个数据集中都执行此操作。

    如果在你的数据集中找到了该文档，请删除 `populateSecrets.js`。

    <Callout type="warn">
      这些凭据会存储在你的 Sanity 数据库中。默认情况下，它们存储在 `generaltranslation.secrets` 文档中，而该文档默认是私有的，即使在公开数据集中也是如此。
      不过，如果你担心这些信息会暴露给 Studio 的已认证用户，可以使用[基于角色的访问控制](https://www.sanity.io/docs/access-control)来控制对此路径的访问。
    </Callout>
  </Step>

  <Step title="（可选）添加专用的翻译选项卡">
    该 插件 会自动为每个文档添加一个会打开对话框的 **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="基础查询">
    你现有的查询保持不变——无需任何改动：

    ```plaintext
    // 获取所有文章（返回源语言文档）
    *[_type == "article"]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="本地化查询">
    要获取翻译后的文档，请添加 `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) - 完整的配置选项