# General Translation Integrations: Inicio rápido
URL: https://generaltranslation.com/es/docs/integrations/sanity/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Instala gt-sanity, añade el plugin de General Translation a Sanity Studio y traduce tu primer documento.

El plugin `gt-sanity` traduce documentos desde Sanity Studio. Admite la localización a nivel de documento y a nivel de campo; este Inicio rápido usa la configuración predeterminada a nivel de documento, donde cada traducción es un documento independiente con un campo `language` y un documento `translation.metadata` gestionado por `@sanity/document-internationalization`.

## Antes de empezar [#before-start]

Necesitas:

* Sanity Studio 6.9.2 o una versión posterior. Los estudios con Sanity 6.0 a 6.8 todavía usan la generación 3 de `@sanity/ui` y deben permanecer en `gt-sanity` 3.1.x.
* React 19.2.0 o una versión posterior.
* Node.js 22.12 o una versión posterior.
* Un proyecto de Sanity existente.
* Un [ID del proyecto](/docs/platform/dashboard/get-started) de General Translation y una [clave de API](/docs/platform/dashboard/reference/api-keys) de producción.

## Inicio rápido [#quickstart]

### 1. Instala `gt-sanity` [#install]

Instala el plugin en tu proyecto de Sanity Studio. `gt-sanity` resuelve `@sanity/ui`, `@sanity/icons`, `@sanity/schema` y `@sanity/mutator` desde tu Studio como dependencias de pares, de modo que se mantenga una sola copia de cada singleton de runtime de Studio en el árbol. Un Studio de Sanity 6.9.2+ ya proporciona los cuatro.

<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. Añade el plugin [#add-plugin]

Añade `gtPlugin` a `sanity.config.ts`. Configura la configuración regional de origen, las configuraciones regionales de destino y los tipos de documento que se traducirán.

```ts title="sanity.config.ts"
import { defineConfig } from 'sanity';
import { gtPlugin } from 'gt-sanity';

export default defineConfig({
  // ... tu configuración existente
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
    }),
  ],
});
```

Cuando `translateDocuments` incluye tipos de documento, el plugin añade automáticamente el plugin `@sanity/document-internationalization`: insignias de idioma, un menú de traducción en la barra de herramientas del documento y plantillas de documentos por idioma. Establece `showDocumentInternationalization: false` para desactivarlo.

### 3. Añade un campo de idioma [#language-field]

Todos los tipos de documento que traduzcas con localización a nivel de documento necesitan un campo de idioma. De forma predeterminada, se llama `language`.

```ts title="schema/article.ts"
import { defineField, defineType } from 'sanity';

export const articleType = defineType({
  name: 'article',
  title: 'Article',
  type: 'document',
  fields: [
    // ... tus campos existentes
    defineField({
      name: 'language',
      type: 'string',
      readOnly: true,
      hidden: true,
    }),
  ],
});
```

Si defines un [`languageField`](/docs/integrations/sanity/reference/plugin-configuration#language-field) personalizado en las opciones del plugin, usa ese nombre en tu schema en lugar de `language`.

### 4. Guarda las credenciales [#credentials]

El plugin lee tu clave de API de General Translation y el ID del proyecto desde un documento privado de Sanity. Crea un archivo temporal `populateSecrets.js` en la carpeta de tu Studio.

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

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

client.createOrReplace({
  // El `.` inicial en este _id mantiene el documento privado,
  // incluso en un conjunto de datos público.
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslationSettings',
  secret: process.env.GT_API_KEY,
  project: process.env.GT_PROJECT_ID,
});
```

Ejecuta el script con tus credenciales:

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

El `_id` del documento debe coincidir con el `secretsNamespace` del plugin (valor predeterminado: `generaltranslation.secrets`). El plugin lee el campo `secret` como la clave de API y el campo `project` como el ID del proyecto.

Verifica que el documento exista con la herramienta Vision en tu Studio:

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

Si usas varios conjuntos de datos, repite este paso para cada uno. Después de verificarlo, elimina `populateSecrets.js`.

<Callout type="warn">
  Un `.` inicial mantiene este documento fuera de las consultas no autenticadas a conjuntos de datos públicos, pero el acceso autenticado a Studio sigue estando sujeto a los roles de tu proyecto de Sanity. Usa el [control de acceso basado en roles de Sanity](https://www.sanity.io/docs/access-control) para que solo los usuarios que necesiten la integración puedan leer el conjunto de datos, y nunca hagas commit del script ni de las credenciales.
</Callout>

### 5. Traducir un documento [#translate-document]

1. Abre un documento en el idioma de origen en Sanity Studio.
2. Haz clic en **Traducir** en la barra de acciones del documento.
3. Selecciona las configuraciones regionales de destino.
4. Haz clic en **Traducir**.

Con esta configuración a nivel de documento, el plugin consulta periódicamente si hay traducciones completadas y las importa automáticamente como borradores. La aplicación de parches a referencias y la publicación están desactivadas de forma predeterminada; usa los controles del diálogo o configura su estado inicial con [`autoPatchReferences`](/docs/integrations/sanity/reference/plugin-configuration#auto-patch-references) y [`autoPublish`](/docs/integrations/sanity/reference/plugin-configuration#auto-publish).

Revisa los documentos importados en la perspectiva **Borradores** de Sanity y publícalos antes de realizar consultas desde un frontend que solo use contenido publicado.

(Consulta las guías completas para [traducir contenido](/docs/integrations/sanity/guides/translating-content) y [administrar traducciones](/docs/integrations/sanity/guides/managing-translations)).

### 6. Consultar contenido traducido [#query-content]

Con esta configuración a nivel de documento, las traducciones se almacenan como documentos separados con un campo de idioma. Para obtener contenido traducido, filtra por el campo de idioma.

<Tabs items={['Consulta de origen', 'Consulta localizada']}>
  <Tab value="Consulta de origen">
    ```text
    // Los documentos del idioma de origen no establecen el campo de idioma de forma predeterminada
    *[_type == "article" && !defined(language)]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Consulta localizada">
    ```text
    // Obtener artículos en español
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }
    ```
  </Tab>
</Tabs>

(Consulta [Consulta de traducciones](/docs/integrations/sanity/guides/querying-translations) para ver más patrones de consulta).

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