# General Translation Platform: translate
URL: https://generaltranslation.com/es/docs/platform/core/reference/gt-class-methods/translation/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Traduce una cadena o una entrada de contenido estructurado a una configuración regional de destino con General Translation. Referencia de la API de translate.

`translate` es el método principal de traducción de una instancia de [GT](/docs/platform/core/reference/gt-class/constructor), para traducir una sola cadena o una entrada de contenido estructurado por vez.

## Descripción general [#overview]

Usa `translate` en una instancia configurada de [`GT`](/docs/platform/core/reference/gt-class/constructor) para traducir una entrada. Pasa el contenido que quieres traducir y una cadena de configuración regional de destino (forma abreviada) o un objeto de opciones. Devuelve una promesa que se resuelve con un [`TranslationResult`](/docs/platform/core/reference/types/translation-result).

```typescript
const gt = new GT({ apiKey: 'your-api-key', projectId: 'your-project-id' });

const result = await gt.translate('Hello, world!', 'es');
```

Firma:

```typescript
translate(
  source: TranslateManyEntry,
  options: string | TranslateOptions,
  timeout?: number
): Promise<TranslationResult>
```

*Nota: `translate` requiere un `apiKey` (o `devApiKey`) y `projectId` en la instancia de GT. Internamente, llama a [`translateMany`](/docs/platform/core/reference/gt-class-methods/translation/translate-many) con una sola entrada.*

## Cómo funciona [#how-it-works]

* **Detección de contenido.** El `source` se detecta como texto sin formato, un mensaje ICU, un mensaje con formato i18next o contenido JSX estructurado, según su estructura y los metadatos `dataFormat` que proporciones.
* **Documentos completos.** Establece [`metadata.fileFormat`](/docs/platform/core/reference/types/entry-metadata#file-format) en `'MD'` o `'MDX'` para analizar y traducir un documento completo preservando su estructura. El documento debe ser una cadena con `dataFormat: 'STRING'`, que es el valor predeterminado, y no puede usar `maxChars`. Una entrada de documento falla en lugar de devolver una salida parcial cuando falla un fragmento o el documento traducido no es válido.
* **Resolución de la configuración regional.** La configuración regional de destino se valida conforme a BCP 47. Se aplica cualquier [`customMapping`](/docs/platform/core/reference/types/custom-mapping) de la instancia y se envía el código de configuración regional canónico a la API.
* **Forma abreviada de opciones.** Pasar una cadena para `options` es una forma abreviada de `{ targetLocale: string }`, por lo que `gt.translate('Hello', 'es')` y `gt.translate('Hello', { targetLocale: 'es' })` son equivalentes.

## Parámetros [#parameters]

| Parámetro             | Descripción                                                                                  | Tipo                                                                             | Opcional | Predeterminado |
| --------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------- | -------------- |
| [`source`](#source)   | Contenido que se va a traducir: una `string` o un objeto con `source` y `metadata` opcional. | [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) | No       | —              |
| [`options`](#options) | `string` con la configuración regional de destino, o un objeto de opciones.                  | `string \| TranslateOptions`                                                     | No       | —              |
| [`timeout`](#timeout) | Tiempo de espera de la solicitud en milisegundos.                                            | `number`                                                                         | Sí       | —              |

### `source` [#source]

**Tipo** [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) · **Obligatorio**

El contenido que se va a traducir. Pasa una cadena de texto simple o un objeto con `source` (el [`Content`](/docs/platform/core/reference/types/content)) y `metadata` opcional (un [`EntryMetadata`](/docs/platform/core/reference/types/entry-metadata) que aporta contexto, `dataFormat` y otras indicaciones para la traducción).

### `options` [#options]

**Tipo** `string | TranslateOptions` · **Obligatorio**

Una cadena con la configuración regional de destino, como `'es'`, o un objeto de opciones:

```typescript
type TranslateOptions = {
  targetLocale: string; // configuración regional a la que traducir
  sourceLocale?: string; // reemplaza el sourceLocale de la instancia
  modelProvider?: string; // sugerencia opcional de proveedor de modelo
};
```

### `timeout` [#timeout]

**Type** `number` · **Opcional**

Tiempo de espera de la solicitud en milisegundos. Si se omite, se usa el valor predeterminado de la instancia.

## Devuelve [#returns]

**Tipo** `Promise<TranslationResult>`

Se resuelve con un [`TranslationResult`](/docs/platform/core/reference/types/translation-result): una unión discriminada de un resultado correcto (con `translation` y `locale`) y un resultado de error (con `error` y `code`). Comprueba siempre `success` antes de leer la traducción.

## Ejemplos [#examples]

```typescript
// Traducción de cadenas simple (forma abreviada de configuración regional)
const result = await gt.translate('Welcome to our application', 'fr');

if (result.success) {
  console.log(result.translation); // "Bienvenue dans notre application"
} else {
  console.error(`Translation failed: ${result.error}`);
}
```

```typescript
// Con un objeto de opciones y configuración regional de origen explícita
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```

```typescript
// Con metadatos de origen (plural ICU + contexto)
const result = await gt.translate(
  {
    source: '{count, plural, other {{count} items}}',
    metadata: { dataFormat: 'ICU', context: 'Item count display' },
  },
  { targetLocale: 'es' }
);
```

```typescript
// Traducir un documento Markdown completo.
const result = await gt.translate(
  {
    source: '# Welcome\n\nRead the [guide](/guide).',
    metadata: { fileFormat: 'MD' },
  },
  { sourceLocale: 'en', targetLocale: 'es' }
);
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.