# sanity: Configuración
URL: https://generaltranslation.com/es/docs/sanity/guides/configuration.mdx
---
title: Configuración
description: Configura el plugin gt-sanity para tu proyecto de Sanity
---

## Descripción general

La función `gtPlugin` acepta un objeto de configuración para personalizar el comportamiento de la traducción, la configuración regional y la gestión de documentos.

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'], // Reemplaza con tus configuraciones regionales de destino
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
    }),
  ],
});
```

## Configuración básica

### Configuración regional de origen y configuraciones regionales de destino

Define tu idioma de origen y las configuraciones regionales de destino:

```typescript
gtPlugin({
  sourceLocale: 'en', // Idioma de origen del contenido
  locales: ['es', 'zh', 'ja'], // Idiomas de destino para la traducción
});
```


### Uso de `defaultLocale` desde `gt.config.json`

Si ya tienes un `gt.config.json` (p. ej., por usar `gt-next` o `gt-react`), puedes incorporarlo directamente en la configuración del plugin. El campo `defaultLocale` se acepta como alias de `sourceLocale`:

```typescript
import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig, // { defaultLocale: 'en', locales: ['es', 'zh', 'ja'] }
});
```

Si se proporcionan tanto `sourceLocale` como `defaultLocale`, `sourceLocale` prevalece.


### Campo de idioma

Especifica qué campo almacena la configuración regional del documento. El valor predeterminado es `'language'`:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale', // Por defecto, los documentos usan el campo 'language'. Aquí usamos 'locale' en su lugar.
});
```


## Filtrado de documentos

### Traducir tipos de documentos concretos

Limita la traducción a tipos de documentos concretos:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'page' }, { type: 'post' }],
});
```


### Traducir documentos específicos

Especifica los ID de documentos concretos:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [
    { documentId: 'homepage' },
    { documentId: 'about-page' },
  ],
});
```


## Documentos singleton

Los documentos singleton son documentos de Sanity que existen como una única instancia con variantes traducidas. Configura cómo se nombran las versiones traducidas:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'], // Lista de IDs de documentos singleton
  singletonMapping: (docId, locale) => `${docId}-${locale}`, // Función opcional para personalizar los ids de los documentos singleton traducidos
});
```

De forma predeterminada, las traducciones de los singletons tendrán `id` generados aleatoriamente, a menos que se proporcione `singletonMapping`.


## Ignorar campos

Campos que no quieres traducir ni enviar a la API de GT, pero que aun así deben copiarse del documento de origen a la traducción. Los campos ignorados se eliminan antes de la serialización (por lo que el contenido nunca se envía a la API) y luego se restauran desde el documento de origen una vez creado el documento traducido.

Usa `ignoreFields` para campos como categorías, etiquetas o metadatos internos que deben tener el mismo valor tanto en el documento de origen como en el traducido, pero que no necesitan traducirse:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  ignoreFields: [
    { fields: [{ property: '$.category' }] },       // misma categoría en todos los idiomas
    { fields: [{ property: '$..linkType' }] },       // metadatos internos de enlace
    { fields: [{ property: '$..frequencies.default' }] },
  ],
});
```

`property` es una expresión [JSONPath](https://goessner.net/articles/JsonPath/) que coincide con uno o varios campos de los documentos.
`type` es un parámetro opcional para filtrar aún más los campos que se deben ignorar por tipos específicos.


## Deduplicación de campos

Campos que no quieres traducir ni enviar a la API de GT, pero que aun así deben copiarse del documento de origen y ser únicos cuando se crea por primera vez un documento traducido. Los campos deduplicados se eliminan antes de la serialización y luego se restauran a partir del documento de origen con la configuración regional de destino añadida.

Usa `dedupeFields` para slugs de Sanity u otros identificadores de tipo cadena que deben seguir basándose en el valor de origen, pero ser únicos por idioma:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  dedupeFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] }, // "about" pasa a ser "about-es"
  ],
});
```

En los campos slug de Sanity, el plugin actualiza el valor `current` del objeto slug. Por ejemplo, `{ _type: 'slug', current: 'about' }` pasa a ser `{ _type: 'slug', current: 'about-es' }` cuando se crea el documento en español. Si un editor cambia más tarde el slug traducido, las futuras importaciones de traducción conservan ese valor editado.

## Omitir campos

Campos que no deben copiarse automáticamente a los documentos traducidos bajo ningún concepto. A diferencia de `ignoreFields` (que conserva el valor de origen en la traducción), `skipFields` elimina por completo del documento traducido los campos que coincidan.

Usa `skipFields` para campos como URL canónicas de SEO, metadatos exclusivos del original o slugs que los editores deben establecer manualmente para cada idioma:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },  // los editores configuran los slugs manualmente por idioma
    { fields: [{ property: '$.canonicalUrl' }] },         // solo relevante en el origen
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],              // datos de depuración exclusivos del origen
    },
  ],
});
```

## Opciones de serialización

Amplía el comportamiento de serialización predeterminado:

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalSerializers: {
    // Serializadores adicionales para marcas (anotaciones personalizadas)
    marks: {
      link: ({ value, children }) =>
        attachGTData(`<a>${children}</a>`, value, 'markDef'),
      inlineMath: ({ value, children }) =>
        attachGTData(`<span>${children}</span>`, value, 'markDef'),
    },
  },
});
```

Consulta la [guía de serialización](/docs/sanity/guides/serialization) para más información.


## Ejemplo completo

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

export default defineConfig({
  name: 'default',
  title: 'My Project',
  projectId: 'your-project-id',
  dataset: 'production',

  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja', 'zh'],
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [
        {
          fields: [{ property: '$.publishedAt' }],
        },
      ],
      dedupeFields: [
        {
          fields: [{ property: '$.slug', type: 'slug' }],
        },
      ],
      skipFields: [
        {
          fields: [{ property: '$.internalNotes' }],
        },
      ],
    }),
  ],

  schema: {
    types: schemaTypes,
  },
});
```

## Próximos pasos

* [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