# sanity: Guía de inicio rápido de Sanity
URL: https://generaltranslation.com/es/docs/sanity/guides/quickstart.mdx
---
title: Guía de inicio rápido de Sanity
description: Integra General Translation con Sanity CMS usando gt-sanity
---

**Requisitos previos:** Sanity Studio v5+, React 19+, proyecto de Sanity existente

<Callout type="warn">
  **Se requieren cambios en el esquema y en el frontend.** Cada tipo de documento que traduzcas debe incluir un campo `language` en su esquema; consulta la [configuración del campo language](/docs/sanity#language-field) para obtener más detalles.
  Las traducciones se almacenan como documentos independientes, por lo que también tendrás que actualizar las consultas de tu frontend para obtener la versión correcta del idioma.
  Consulta [consultar contenido traducido](#querying-translated-content) más abajo para ver ejemplos.
</Callout>

## Instalación

Instala el paquete `gt-sanity` en el directorio de tu Studio de 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>

## Configuración

<Steps>
  <Step title="Agregar el plugin a tu configuración de Sanity">
    ```typescript title="sanity.config.ts"
    import { defineConfig } from 'sanity'
    import { gtPlugin } from 'gt-sanity'

    export default defineConfig({
      // ... your existing config
      plugins: [
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja'], // Replace with your target locales
          translateDocuments: [{ type: 'article' }, { type: 'page' }], // Document types to enable translations for
        })
      ]
    })
    ```

    Cuando se proporciona `translateDocuments`, el plugin agrega automáticamente funciones de internacionalización de documentos de @sanity: insignias de idioma, un menú de traducción en la barra de herramientas del documento y plantillas de documento por idioma. Establece `showDocumentInternationalization: false` para desactivar esto.
  </Step>

  <Step title="Agregar un campo de idioma a tus esquemas">
    Cada tipo de documento que traduzcas debe tener un campo `language`:

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

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

    Si configuraste un `languageField` personalizado en las opciones del plugin, usa ese nombre en lugar de `'language'`.
  </Step>

  <Step title="Configurar credenciales de API">
    En la carpeta de tu Studio, crea un archivo llamado `populateSecrets.js` con el siguiente contenido:

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

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

    client.createOrReplace({
      // The `.` in this _id will ensure the document is private
      // even in a public dataset!
      _id: 'generaltranslation.secrets',
      _type: 'generaltranslationSettings',
      secret: process.env.GT_API_KEY,
      project: process.env.GT_PROJECT_ID,
    });
    ```

    A continuación, obtén una clave de API de producción en [dash.generaltranslation.com](https://dash.generaltranslation.com).

    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
    ```

    Verifica que el documento se creó usando la herramienta Vision en el Studio y consulta `*[_id == 'generaltranslation.secrets']`.

    Nota: Si tienes múltiples datasets, tendrás que hacer esto en todos ellos.

    Si el documento se encontró en tu(s) dataset(s), elimina `populateSecrets.js`.

    <Callout type="warn">
      Estas credenciales se almacenarán en tu base de datos de Sanity. Por defecto, se almacenan en el documento `generaltranslation.secrets`, que es privado por defecto, incluso en un dataset público.
      Sin embargo, si te preocupa que esto sea accesible para usuarios autenticados de tu Studio, puedes controlar el acceso a esta ruta con [control de acceso basado en roles](https://www.sanity.io/docs/access-control).
    </Callout>
  </Step>

  <Step title="(Opcional) Agregar una pestaña dedicada de Translations">
    El plugin agrega automáticamente una acción **traducir** a cada documento que abre un diálogo. Si también quieres una vista de pestaña dedicada, agrega el componente `TranslationsTab` a las vistas de tu documento:

    ```typescript title="sanity.config.ts"
    import { defineConfig } from 'sanity'
    import { structureTool } from 'sanity/structure'
    import { gtPlugin, TranslationsTab } from 'gt-sanity'

    export default defineConfig({
      // ... your config
      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>

## Uso

Una vez configurado, puedes traducir documentos directamente desde tu Sanity Studio:

1. Abre cualquier documento en tu Studio
2. Haz clic en el botón **Traducir** en la barra de acciones del documento; se abrirá un cuadro de diálogo
3. Selecciona los idiomas de destino
4. Haz clic en **Generate Translations** para enviar el contenido a traducir
5. De forma predeterminada, el plugin importará automáticamente las traducciones en tu documento en cuanto estén listas.
6. Además, los documentos importados se analizarán automáticamente en busca de referencias a otros documentos y se actualizarán automáticamente para que apunten a las traducciones correctas de esos documentos.

## Consultar contenido traducido

El plugin almacena las traducciones como documentos independientes con un campo `language` (configurable mediante [`languageField`](/docs/sanity/api/plugin-config)). Tus consultas GROQ actuales para el contenido fuente seguirán funcionando sin cambios.

Para obtener contenido traducido, filtra por el campo `language`:

<Tabs items={["Consulta base", "Consulta por idioma"]}>
  <Tab value="Consulta base">
    Tus consultas actuales se mantienen igual: no necesitas hacer cambios.

    ```plaintext
    // Obtener todos los artículos (devuelve documentos en el idioma fuente)
    *[_type == "article"]{
      title,
      slug,
      body
    }
    ```
  </Tab>

  <Tab value="Consulta por idioma">
    Para obtener documentos traducidos, agrega el filtro `language`:

    ```plaintext
    // Obtener artículos en español
    *[_type == "article" && language == "es"]{
      title,
      slug,
      body
    }

    // Obtener un artículo concreto en un idioma concreto
    *[_type == "article" && slug.current == "hello-world" && language == "es"][0]{
      title,
      body
    }

    // Obtener artículos en cualquier idioma
    *[_type == "article"]{
      title,
      slug,
      body,
      language
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
  De forma predeterminada, los documentos fuente no tienen establecido el campo `language`. Para consultar el contenido fuente junto con las traducciones, puedes filtrar por los documentos donde `language` sea tu configuración regional de origen o no esté definido: `language == "en" || !defined(language)`.
</Callout>

## Próximos pasos

* [Guía de configuración](/docs/sanity/guides/configuration) - Personaliza el comportamiento del plugin
* [Guía de serialización](/docs/sanity/guides/serialization) - Define reglas de serialización personalizadas
* [Referencia de la API](/docs/sanity/api/plugin-config) - Opciones de configuración completas