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

**Requisitos previos:** Sanity Studio v3+, proyecto de Sanity existente

<Callout type="warn">
  **Se requieren cambios en el frontend.** El plugin `gt-sanity` funciona con tus esquemas de Sanity existentes; no se necesitan campos de i18n ni cambios en el modelo de datos.
  Sin embargo, las traducciones se almacenan como documentos separados, por lo que tendrás que actualizar tus consultas del frontend para obtener la versión en el idioma correcto.
  Consulta [Consultar el contenido traducido](#querying-translated-content) a continuación para ver ejemplos.
</Callout>

## Instalación

Instala el paquete `gt-sanity` en el directorio de tu estudio 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="Agrega 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({
      // ... tu configuración existente
      plugins: [
        gtPlugin({
          sourceLocale: 'en',
          locales: ['es', 'zh', 'ja'] // Reemplaza con tus locales de destino
        })
      ]
    })
    ```
  </Step>

  <Step title="Configura las credenciales de la 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: '2025-09-15' });

    client.createOrReplace({
      // El `.` en este _id garantizará que el documento sea 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,
    });
    ```

    A continuación, obtén una clave 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 haya creado con la Vision Tool en Studio y consulta `*[_id == 'generaltranslation.secrets']`.

    Nota: Si tienes varios conjuntos de datos, tendrás que hacer esto en todos ellos.

    Si se encontró el documento en tus conjuntos de datos, 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 conjunto de datos público.
      Sin embargo, si te preocupa que esto quede expuesto a 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="Agrega la pestaña Traducciones a los documentos">
    Configura la estructura de tus documentos para incluir la vista de traducciones:

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

    export default defineConfig({
      // ... tu configuración
      plugins: [
        structureTool({
          structure: (S) =>
            S.list()
              .title('Contenido')
              .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'] // Reemplaza con tus locales de destino
        })
      ]
    })
    ```
  </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 la pestaña **General Translation**
3. Selecciona los idiomas de destino
4. Haz clic en **Generar traducciones** para enviar el contenido para su traducción
5. Por defecto, 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 para detectar referencias a otros documentos y se actualizarán automáticamente para que apunten a las traducciones correctas de esos documentos.

## Consultar el contenido traducido

El plugin almacena las traducciones como documentos separados con un campo `language` (configurable mediante [`languageField`](/docs/sanity/api/plugin-config)). Tus consultas GROQ existentes para el contenido de origen siguen funcionando igual, sin cambios.

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

<Tabs items={["Consulta base", "Consulta localizada"]}>
  <Tab value="Consulta base">
    Tus consultas existentes siguen igual; no hace falta cambiar nada:

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

  <Tab value="Consulta localizada">
    Para obtener documentos traducidos, añade un filtro por `language`:

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

    // Obtener un artículo específico en un idioma específico
    *[_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">
  Los documentos de origen no tienen el campo `language` establecido por defecto. Para consultar el contenido de origen junto con las traducciones, puedes filtrar los documentos donde `language` sea tu configuración regional de origen o no esté establecido: `language == "en" || !defined(language)`.
</Callout>

## Siguientes pasos

* [Guía de configuración](/docs/sanity/guides/configuration) - Personaliza el comportamiento del plugin
* [Guía de serialización](/docs/sanity/guides/serialization) - Reglas de serialización personalizadas
* [Referencia de la API](/docs/sanity/api/plugin-config) - Todas las opciones de configuración