# sanity: 简介
URL: https://generaltranslation.com/zh/docs/sanity.mdx
---
title: 简介
description: General Translation Sanity CMS plugin 概述
---

## 概述

`gt-sanity` plugin 可直接集成到 Sanity Studio v5+。
它为你的 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'],
    }),
  ],
});
```


## 工作原理

该 plugin 采用 Sanity 的[文档级本地化](https://www.sanity.io/docs/studio/localization)方案：对于每个源文档，它都会创建单独的翻译后的文档，并将 `language` 字段设为目标区域设置。

<Callout type="warn">
  **需要修改 schema 和查询。** 你要翻译的每种文档类型都必须在其 schema 中包含 `language` 字段 (见下文) 。
  你还需要更新前端查询，以获取正确的语言版本。
  setup 和 GROQ 查询示例请参阅[快速入门](/docs/sanity/guides/quickstart#querying-translated-content)。
</Callout>

### 语言字段

你要翻译的每种文档类型都必须定义一个 `language` 字段：

```typescript
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` 名称，字段名必须保持一致。

## 主要特性

### 文档翻译

将整个文档翻译成多个目标区域设置。该 plugin 可处理 Portable Text、嵌套对象、数组和自定义 Schema 类型。

### 批量操作

一次翻译多个文档或整个站点。可导入全部译文、仅导入缺失的译文，或按区域设置选择性导入。

### 智能序列化

文档会被序列化为 HTML 以供翻译，同时保留其结构和元数据。
对于语法结构不同的语言，系统会自动调整译文结构，使其更符合目标语言的表达习惯。

自定义序列化器可让你控制特定字段类型的处理方式。

## Plugin UI

该 plugin 提供三个主要的 UI 组件：

### 翻译操作 (对话框) 

系统会自动为每个文档添加“翻译”操作。点击文档操作栏中的 **翻译** 按钮，即可打开包含完整翻译界面的对话框，无需额外配置。

### 翻译标签页 (可选) 

![TranslationsTab](https://assets.gtx.dev/docs/sanity-translations-tab.png)

你也可以通过 `structureTool` 将 `TranslationsTab` 添加为专用的文档视图。这样即可提供与对话框相同的翻译功能，并以标签页的形式嵌入文档编辑器中。

setup 说明请参阅[快速入门](/docs/sanity/guides/quickstart#configuration)。

### 翻译页面

![TranslationsPage](https://assets.gtx.dev/docs/sanity-translations-page.png)

“翻译页面”是 Sanity 中的一个页面，用于从全站范围查看整个站点的翻译情况。
在这个集中管理页面中，您可以：

* 批量为所有文档生成翻译
* 批量导入所有文档的翻译
* 批量导入特定文档的翻译
* 修复语言引用以及指向其他文档的链接
* 批量发布所有文档的翻译

## 支持的内容类型

plugin 支持大多数 Sanity schema 类型。

自定义类型可通过[自定义序列化器](/docs/sanity/guides/serialization)进行配置。

像 slug 这样的字段可以通过 `dedupeFields` 进行配置，这样新的翻译后的文档会以源派生值和唯一的区域设置后缀开头，例如 `about-es` 或 `about-fr`。

## 后续步骤

* [快速入门](/docs/sanity/guides/quickstart) - 开始安装和设置
* [设置指南](/docs/sanity/guides/configuration) - 自定义 plugin 的行为
* [序列化指南](/docs/sanity/guides/serialization) - 自定义序列化规则