# 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. 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 `402` and `429` responses. A `402` response means the Organization's billing account is blocked, or its plan usage limit, monthly spend limit, or credit balance does not cover the request. 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.
