# General Translation Platform: translate
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/gt-class-methods/translation/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Translate one string or structured content entry into a target locale with General Translation. API reference for translate.

`translate` is the primary translation method on a [GT](/docs/platform/core/reference/gt-class/constructor) instance, for translating one string or structured content entry at a time.

## Overview [#overview]

Call `translate` on a configured [`GT`](/docs/platform/core/reference/gt-class/constructor) instance to translate one entry. Pass the content to translate and either a target locale string (shorthand) or an options object. It returns a promise that resolves to a [`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');
```

Signature:

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

*Note: `translate` requires an API key (including the deprecated `devApiKey` alias), plus `projectId` on the GT instance. Under the hood it calls [`translateMany`](/docs/platform/core/reference/gt-class-methods/translation/translate-many) with a single entry.*

## How it works [#how-it-works]

- **Content detection.** The `source` is detected as plain text, an ICU message, an i18next-style message, or structured JSX content, based on its shape and the `dataFormat` metadata you provide.
- **Whole documents.** Set [`metadata.fileFormat`](/docs/platform/core/reference/types/entry-metadata#file-format) to `'MD'` or `'MDX'` to parse and translate a complete document while preserving its structure. The document must be a string with `dataFormat: 'STRING'`, which is the default, and cannot use `maxChars`. A document entry fails instead of returning partial output when a chunk fails or the translated document is invalid.
- **Locale resolution.** The target locale is validated against BCP 47. Any [`customMapping`](/docs/platform/core/reference/types/custom-mapping) on the instance is applied, and the canonical locale code is sent to the API.
- **Options shorthand.** Passing a string for `options` is shorthand for `{ targetLocale: string }`, so `gt.translate('Hello', 'es')` and `gt.translate('Hello', { targetLocale: 'es' })` are equivalent.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`source`](#source) | Content to translate: a string, or an object with `source` and optional `metadata`. | [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) | No | — |
| [`options`](#options) | Target locale string, or an options object. | `string \| TranslateOptions` | No | — |
| [`timeout`](#timeout) | Request timeout in milliseconds. | `number` | Yes | — |

### `source` [#source]

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

The content to translate. Pass a plain string, or an object with `source` (the [`Content`](/docs/platform/core/reference/types/content)) and optional `metadata` (an [`EntryMetadata`](/docs/platform/core/reference/types/entry-metadata) that adds context, `dataFormat`, and other translation hints).

### `options` [#options]

**Type** `string | TranslateOptions` · **Required**

A target locale string such as `'es'`, or an options object:

```typescript
type TranslateOptions = {
  targetLocale: string; // locale to translate into
  sourceLocale?: string; // overrides the instance sourceLocale
  modelProvider?: string; // validated before fetch
  [key: string]: unknown; // extension metadata, not transport options
};
```

Import [`TranslateOptions`](/docs/platform/core/reference/types/translation-config#translate-options) from `generaltranslation/types`. Unsupported `modelProvider` values reject before fetch. (See [accepted providers and entitlements](/docs/platform/core/reference/types/enqueue-files-options#modelprovider)).

### `timeout` [#timeout]

**Type** `number` · **Optional**

Request timeout in milliseconds; omission or `0` selects 60000 ms. Only numbers are accepted, not `false`. This is separate from [request transport configuration](/docs/platform/core/reference/types/translation-config).

## Returns [#returns]

**Type** `Promise<TranslationResult>`

Resolves to a [`TranslationResult`](/docs/platform/core/reference/types/translation-result) — a discriminated union of a success result (with `translation` and `locale`) and an error result (with `error` and `code`). Always narrow on `success` before reading the translation.

Runtime translation does not retry transport failures, including `429`. Configuration, authentication, HTTP, network, cancellation, and timeout failures can reject the entire call rather than resolve as an item failure. Results retain the service locale rather than restoring configured aliases. (See [Errors](/docs/platform/core/reference/api-client#types-errors)).

## Examples [#examples]

```typescript
// Simple string translation (locale shorthand)
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
// With an options object and explicit source locale
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```

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

```typescript
// Translate a complete Markdown document.
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.