# General Translation Integrations: Configurar Sanity
URL: https://generaltranslation.com/es/docs/integrations/sanity/guides/configuring-sanity.mdx
---

title: Configurar Sanity
description: "Cómo configurar el plugin gt-sanity de General Translation: esta guía abarca locales, filtros de documentos, localización a nivel de campo, credenciales, campos de idioma y documentos singleton."
related:
  links:
    - /docs/integrations/sanity/guides/translating-content
    - /docs/integrations/sanity/guides/managing-translations
    - /docs/integrations/sanity/guides/querying-translations

---

Configura cómo funciona General Translation dentro de Sanity Studio con la función `gtPlugin`.

Esta guía abarca las opciones más comunes. Para ver la lista completa, consulta la [referencia de configuración del plugin](/docs/integrations/sanity/reference/plugin-configuration).

## Agrega el plugin [#add-plugin]

Agrega `gtPlugin` a la configuración de Studio. Este paso también se trata en el [Quickstart](/docs/integrations/sanity/quickstart).

```ts 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' }],
    }),
  ],
});
```

## Define la configuración regional de origen y las de destino [#set-locales]

Usa `sourceLocale` para el idioma de origen y `locales` para las configuraciones regionales de destino.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
});
```

Si ya tienes un `gt.config.json`, puedes incluirlo en la configuración del plugin con el operador spread. `defaultLocale` también se acepta como alias de `sourceLocale`.

```ts title="sanity.config.ts"
import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig,
});
```

La configuración regional de origen se determina en este orden: `sourceLocale`, luego `defaultLocale` y, después, el valor predeterminado de la biblioteca. Si se configuran tanto `sourceLocale` como `defaultLocale`, prevalece `sourceLocale`.

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

Las traducciones se almacenan como documentos separados. El plugin usa un campo de idioma para registrar la configuración regional de cada documento. De forma predeterminada, el campo se llama `language`.

```ts 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,
    }),
  ],
});
```

Para usar un nombre de campo distinto, configura `languageField` y usa el mismo nombre en tu schema.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale',
});
```

## Elige qué documentos traducir [#choose-documents]

Usa `translateDocuments` para filtrar qué documentos se pueden traducir. Acepta filtros por tipo de documento, por ID de documento o cadenas abreviadas de tipo.

```ts
// Por tipo de documento
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'page' }, { type: 'post' }],
});
```

```ts
// Por ID de documento específico
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ documentId: 'homepage' }, { documentId: 'about-page' }],
});
```

```ts
// Cadenas de tipo en forma abreviada
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: ['article', 'page'],
});
```

Las entradas de tipo `string` se tratan como `{ type: '<string>' }`. `showDocumentInternationalization` usa las entradas de `type` para decidir qué tipos de schema reciben insignias de idioma y plantillas, por lo que se requieren filtros por tipo de documento para habilitar esas funciones.

## Configurar la localización a nivel de campo [#field-level]

De forma predeterminada, `gt-sanity` traduce a nivel de documento y crea un documento por configuración regional. La localización a nivel de campo almacena el valor de cada configuración regional dentro del mismo documento como una lista internacionalizada (`[{ _key, _type, language, value }]` — con la misma estructura que [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array), por lo que los datos existentes no requieren migración).

Habilita la generación del esquema con `internationalizedArray` (o su alias, `fieldLevelLocalization`) y luego establece `translationLevel` en `'internationalizedArray'`.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'post' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'internationalizedArray',
});
```

El plugin genera tipos de esquema `internationalizedArray*` a partir de `sourceLocale` y `locales`, junto con una interfaz de edición inline para cada configuración regional. Usa los tipos generados en tus esquemas.

```ts
defineField({
  name: 'title',
  type: 'internationalizedArrayString',
});
```

De forma predeterminada, el plugin genera tipos `string` y `text`. Usa `fieldTypes` para añadir `block` (Portable Text) o definiciones de objetos personalizadas.

```ts
internationalizedArray: {
  enabled: true,
  fieldTypes: ['string', 'text', 'block', { name: 'seo', type: 'seoFields' }],
},
```

Para combinar ambas estrategias, establece `translationLevel` en `'mixed'` y enumera en `fieldLevelDocuments` los tipos de documento a nivel de campo.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'mixed',
  fieldLevelDocuments: [{ type: 'siteSettings' }],
});
```

Los tipos de documento localizados en el mismo documento se excluyen automáticamente de `@sanity/document-internationalization`, por lo que no reciben insignias de idioma ni plantillas de documento para cada configuración regional. Durante la importación, el plugin actualiza solo la configuración regional de destino en el documento de origen y conserva todos los demás idiomas.

Consulta la [referencia de configuración del plugin](/docs/integrations/sanity/reference/plugin-configuration#field-level) para ver todas las opciones a nivel de campo.

## Configurar documentos singleton [#singletons]

Usa `singletons` para documentos que existen una sola vez por sitio, como la configuración del sitio o la navegación. `singletonMapping` controla cómo se obtiene el ID del documento del singleton traducido a partir del ID y la configuración regional del documento fuente.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'],
  singletonMapping: (sourceDocumentId, locale) => `${sourceDocumentId}-${locale}`,
});
```

Si omites `singletonMapping`, de forma predeterminada se asignan `sourceDocumentId` y `locale` a `` `${sourceDocumentId}-${locale}` `` (por ejemplo, `siteSettings-es`).

## Guardar credenciales [#store-credentials]

El plugin lee tu clave de API y el ID del proyecto de un documento privado de Sanity cuyo `_id` coincide con `secretsNamespace` (por defecto, `generaltranslation.secrets`). Créalo con un script puntual.

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

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

client.createOrReplace({
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslation.secrets',
  secret: process.env.GT_API_KEY,
  project: process.env.GT_PROJECT_ID,
});
```

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

El campo `secret` se usa como la clave de API y el campo `project` como el ID del proyecto. Para leer credenciales desde otro documento, establece `secretsNamespace` con el `_id` de ese documento.

También puedes pasar `apiKey` y `projectId` directamente a `gtPlugin`, pero se recomienda usar el documento de secretos para que las credenciales no queden en el control de versiones. Cuando ambos están presentes, el documento de secretos tiene prioridad en Runtime.

## Añade la pestaña opcional Traducciones [#translations-tab]

La acción de documento **Traducir** se añade automáticamente. Para mostrar también la pestaña Traducciones dentro del editor de documentos, añade `TranslationsTab` con `structureTool`.

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

export default defineConfig({
  plugins: [
    structureTool({
      defaultDocumentNode: (S) =>
        S.document().views([
          S.view.form(),
          S.view.component(TranslationsTab).title('General Translation'),
        ]),
    }),
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
    }),
  ],
});
```
## Next steps

- /docs/integrations/sanity/guides/translating-content
- /docs/integrations/sanity/guides/managing-translations
- /docs/integrations/sanity/guides/querying-translations