# 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 para locales, filtros de documentos, localización a nivel de campo, credenciales 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`. El plugin elimina la configuración regional de origen y las entradas duplicadas de `locales`, por lo que un `gt.config.json` compartido puede incluir de forma segura la configuración regional predeterminada.

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

Las traducciones a nivel de documento 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`. La localización a nivel de campo no usa este campo.

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

La localización a nivel de campo se basa en [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array), el plugin de referencia de Sanity. `gtPlugin` lo configura a partir de `sourceLocale` y `locales`, y el plugin nativo registra los tipos de schema `internationalizedArray*` y la interfaz de edición de Studio — los botones de añadir para cada idioma, las etiquetas de idioma y las acciones de campo se comportan exactamente igual que con el plugin independiente. Usa los tipos registrados en tus esquemas.

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

De forma predeterminada, el plugin registra 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' }],
},
```

Si ya registras `sanity-plugin-internationalized-array` en tu Studio por tu cuenta, mantén tu configuración y deja `internationalizedArray` sin configurar para que los tipos de schema solo se registren una vez. Traducción lee y escribe los datos almacenados `{ _key, _type, language, value }` independientemente de qué instancia del plugin haya registrado los tipos, así que establecer `translationLevel` (y `translateDocuments`) es todo lo que GT necesita.

```ts
import { internationalizedArray } from 'gt-sanity';

plugins: [
  internationalizedArray({
    languages: [
      { id: 'en', title: 'English' },
      { id: 'es', title: 'Spanish' },
    ],
    fieldTypes: ['string'],
  }),
  gtPlugin({
    sourceLocale: 'en',
    locales: ['es'],
    translateDocuments: [{ type: 'post' }],
    translationLevel: 'internationalizedArray',
  }),
],
```

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.

## Excluir campos de la traducción [#exclude-fields]

Marca un campo en tu schema para que su contenido no se traduzca. Establece `options.gt.exclude` en la definición del campo.

```ts title="schema/article.ts"
defineField({
  name: 'internalNotes',
  type: 'string',
  options: { gt: { exclude: true } },
});
```

Los campos excluidos nunca se envían a traducción, por lo que los documentos traducidos conservan intacto el valor de origen. La exclusión se aplica a cualquier nivel de anidación.

El plugin también respeta las opciones de exclusión de los plugins estándar de localización de Sanity, así que, si tu schema ya las usa, no necesitas añadir una segunda marca:

* `options.documentInternationalization.exclude` de `@sanity/document-internationalization`
* `options.aiAssist.exclude` de `@sanity/assist`
* la propiedad de campo heredada `localize: false`

Para excluir todas las instancias de un tipo personalizado, establece la opción en la propia definición del tipo.

```ts title="schema/objects/legalDisclaimer.ts"
export const legalDisclaimer = defineType({
  name: 'legalDisclaimer',
  type: 'object',
  // Excluye este tipo en todos los lugares donde se utiliza
  options: { gt: { exclude: true } },
  fields: [
    defineField({ name: 'jurisdiction', type: 'string' }),
    defineField({ name: 'text', type: 'text' }),
  ],
});
```

Para las reglas que se aplican a documentos por ID o transforman valores según la configuración regional —como la deduplicación de `slug`— usa en su lugar las opciones [`ignoreFields`, `skipFields` y `dedupeFields`](/docs/integrations/sanity/reference/plugin-configuration#field-matchers) a nivel del plugin.

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