# sanity: Configuración del plugin
URL: https://generaltranslation.com/es/docs/sanity/api/plugin-config.mdx
---
title: Configuración del plugin
description: Referencia de la API de las opciones de configuración de gtPlugin
---

## Descripción general

La función `gtPlugin` configura General Translation para tu estudio de Sanity.

```typescript
import { gtPlugin } from 'gt-sanity'

gtPlugin(config: GTPluginConfig)
```


## GTPluginConfig

<TypeTable
  type={{
  sourceLocale: {
    type: 'string',
    description: 'Código del idioma de origen (p. ej., "en"). Usa defaultLocale como valor predeterminado si no se proporciona.',
    optional: true,
  },
  defaultLocale: {
    type: 'string',
    description: 'Alias de sourceLocale. Se acepta para que puedas expandir gt.config.json directamente. sourceLocale tiene prioridad si ambos están definidos.',
    optional: true,
  },
  locales: { type: 'string[]', description: 'Lista de códigos de configuración regional de destino' },
  apiKey: {
    type: 'string',
    description: 'Clave de API de GT (opcional si usas un documento de secretos)',
    optional: true,
  },
  projectId: {
    type: 'string',
    description: 'ID del proyecto de GT (opcional si usas un documento de secretos)',
    optional: true,
  },
  languageField: {
    type: 'string',
    description: 'Campo del documento que almacena la configuración regional. Valor predeterminado: "language"',
    optional: true,
  },
  singletons: {
    type: 'string[]',
    description: 'ID de documentos tratados como singletons',
    optional: true,
  },
  singletonMapping: {
    type: '(docId: string, locale: string) => string',
    description:
      'Función para generar ID de singletons traducidos. Valor predeterminado: "${docId}-${locale}"',
    optional: true,
  },
  ignoreFields: {
    type: 'IgnoreFields[]',
    description: 'Campos que se excluyen de la traducción. Los campos coincidentes se eliminan antes de la serialización y se restauran desde el documento original después de la traducción.',
    optional: true,
  },
  dedupeFields: {
    type: 'DedupeFields[]',
    description: 'Campos que se excluyen de la traducción y luego se inicializan desde el documento original con la configuración regional de destino añadida al crear un documento traducido.',
    optional: true,
  },
  skipFields: {
    type: 'SkipFields[]',
    description: 'Campos que se eliminan por completo de los documentos traducidos. A diferencia de ignoreFields, estos campos no aparecerán en absoluto en el documento traducido.',
    optional: true,
  },
  translateDocuments: {
    type: "TranslateDocumentFilter[] | string[]",
    description: 'Filtra qué documentos se pueden traducir. Acepta una lista de objetos de filtro o una lista abreviada de cadenas con tipos de documento.',
    optional: true,
  },
  secretsNamespace: {
    type: 'string',
    description:
      'Espacio de nombres para el documento de credenciales. Valor predeterminado: "generaltranslation"',
    optional: true,
  },
  additionalStopTypes: {
    type: 'string[]',
    description: 'Tipos adicionales que se omiten durante la serialización',
    optional: true,
  },
  additionalSerializers: {
    type: 'Record<string, Serializer>',
    description: 'Serializadores HTML personalizados para tipos de bloque',
    optional: true,
  },
  additionalDeserializers: {
    type: 'Record<string, Deserializer>',
    description: 'Deserializadores HTML personalizados',
    optional: true,
  },
  additionalBlockDeserializers: {
    type: 'BlockDeserializer[]',
    description: 'Deserializadores personalizados a nivel de bloque',
    optional: true,
  },
  customMapping: {
    type: "Record<string, string | Partial<LocaleProperties>>",
    description: 'Asignación personalizada de configuraciones regionales para códigos de configuración regional no estándar',
    optional: true,
  },
  showDocumentInternationalization: {
    type: 'boolean',
    description: 'Cuando es true (valor predeterminado), agrega automáticamente el plugin @sanity/document-internationalization con insignias de idioma, menú de traducción y templates por idioma. Requiere translateDocuments.',
    optional: true,
  },
}}
/>

## IgnoreFields

Campos que no se traducen ni se envían a la API, sino que se copian del documento original a la traducción. Úsalo para campos como categorías, etiquetas o metadatos internos que deben tener el mismo valor en todos los idiomas.

```typescript
type IgnoreFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```


### Ejemplo

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  ignoreFields: [
    // Copiar category tal cual en todos los documentos traducidos
    {
      fields: [{ property: '$.category' }],
    },
    // Copiar estos campos tal cual solo para artículos
    {
      documentId: 'article',
      fields: [{ property: '$.tags' }, { property: '$.author' }],
    },
  ],
});
```


## DedupeFields

Campos que no se traducen ni se envían a la API, sino que se copian del documento original con la configuración regional de destino añadida cuando se crea por primera vez un documento traducido. Úsalo para campos que deben comenzar derivados del origen, pero ser únicos en cada documento traducido, como los slugs de Sanity.

```typescript
type DedupeFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```

### Ejemplo

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'fr'],
  dedupeFields: [
    // "about" se convierte en "about-es" y "about-fr"
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
  ],
});
```

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 más adelante un editor cambia el slug traducido, las futuras importaciones de traducción conservarán ese valor editado.

## SkipFields

Campos que se eliminan por completo de los documentos traducidos. A diferencia de `ignoreFields`, estos campos no aparecerán en las versiones traducidas en absoluto. Úsalo para campos como URL canónicas de SEO, metadatos solo del origen o slugs que los editores deban configurar manualmente para cada idioma.

```typescript
type SkipFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```

### Ejemplo

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  skipFields: [
    // Los editores establecerán los slugs manualmente por idioma
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
    // Remove source-only debug data from homepage translations
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],
    },
  ],
});
```

## TranslateDocumentFilter

Filtra qué documentos están disponibles para traducirse:

```typescript
type TranslateDocumentFilter = {
  documentId?: string; // ID de documento específico
  type?: string; // Tipo de documento
};
```


### Ejemplo

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: [
    { type: 'article' },
    { type: 'page' },
    { documentId: 'homepage' },
  ],
});
```


## Serializador

Función personalizada para convertir un bloque de Sanity en HTML:

```typescript
type Serializer = (props: {
  value: any;
  isInline?: boolean;
  children?: string;
}) => string;
```


### Ejemplo

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalSerializers: {
    link: ({ value, children }) =>
      attachGTData(`<a>${children}</a>`, value, 'markDef'),
  },
});
```


## Tipos de exclusión predeterminados

Estos tipos se conservan, pero no se envían para su traducción:

```typescript
const defaultStopTypes = [
  'reference',
  'crossDatasetReference',
  'date',
  'datetime',
  'file',
  'geopoint',
  'image',
  'number',
  'slug',
  'url',
];
```

Añade más mediante `additionalStopTypes`:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalStopTypes: ['codeBlock', 'mathFormula'],
});
```


## Ejemplo completo

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

export default defineConfig({
  plugins: [
    gtPlugin({
      // Obligatorio
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja'],

      // Manejo de documentos
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      singletonMapping: (id, locale) => `${id}_${locale}`,

      // Filtrado
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [{ fields: [{ property: '$.publishedAt' }] }],
      dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }],
      skipFields: [{ fields: [{ property: '$.internalNotes' }] }],

      // Serialización - ¡No uses esto a menos que sepas lo que estás haciendo!
      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'),
        },
      },
    }),
  ],
});
```

## Próximos pasos

* [Guía de configuración](/docs/sanity/guides/configuration) - Patrones de configuración
* [Guía de serialización](/docs/sanity/guides/serialization) - Serialización personalizada