# General Translation Platform: translate
URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/translation/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Перевод одной строки или записи структурированного контента в целевую локаль с помощью General Translation. Справочник API по translate.

`translate` — основной метод перевода у экземпляра [GT](/docs/platform/core/reference/gt-class/constructor), предназначенный для перевода одной строки или записи структурированного контента за один вызов.

## Обзор [#overview]

Вызовите `translate` у настроенного экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor), чтобы перевести одну запись. Передайте содержимое для перевода и либо строку целевой локали (сокращённый синтаксис), либо объект параметров. Метод возвращает Promise, который по завершении выдаёт [`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');
```

Сигнатура:

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

*Примечание: `translate` требует, чтобы в экземпляре GT были указаны `apiKey` (или `devApiKey`) и `projectId`. Внутри он вызывает [`translateMany`](/docs/platform/core/reference/gt-class-methods/translation/translate-many) для одной записи.*

## Как это работает [#how-it-works]

* **Определение содержимого.** `source` распознаётся как обычный текст, ICU-сообщение, сообщение в формате i18next или структурированное JSX-содержимое — в зависимости от его структуры и переданных вами метаданных `dataFormat`.
* **Целые документы.** Укажите в [`metadata.fileFormat`](/docs/platform/core/reference/types/entry-metadata#file-format) значение `'MD'` или `'MDX'`, чтобы разобрать и перевести документ целиком, сохранив его структуру. Документ должен быть строкой с `dataFormat: 'STRING'` (значение по умолчанию) и не может использовать `maxChars`. Если фрагмент не удалось перевести или переведённый документ оказался некорректным, запись документа завершается ошибкой вместо возврата частичного результата.
* **Определение локали.** Целевая локаль проверяется на соответствие BCP 47. Затем применяется любой [`customMapping`](/docs/platform/core/reference/types/custom-mapping), заданный в экземпляре, и в API отправляется канонический код локали.
* **Сокращённая запись для options.** Передача строки в `options` — это сокращённая запись для `{ targetLocale: string }`, поэтому `gt.translate('Hello', 'es')` и `gt.translate('Hello', { targetLocale: 'es' })` равнозначны.

## Параметры [#parameters]

| Параметр              | Описание                                                                       | Тип                                                                              | Необязательно | По умолчанию |
| --------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | ------------- | ------------ |
| [`source`](#source)   | Данные для перевода: строка или объект с `source` и необязательным `metadata`. | [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) | Нет           | —            |
| [`options`](#options) | Строка целевой локали или объект параметров.                                   | `string \| TranslateOptions`                                                     | Нет           | —            |
| [`timeout`](#timeout) | Тайм-аут запроса в миллисекундах.                                              | `number`                                                                         | Да            | —            |

### `source` [#source]

**Тип** [`TranslateManyEntry`](/docs/platform/core/reference/types/translate-many-entry) · **Обязательно**

Содержимое для перевода. Передайте обычную строку или объект с `source` (тип [`Content`](/docs/platform/core/reference/types/content)) и необязательным `metadata` ([`EntryMetadata`](/docs/platform/core/reference/types/entry-metadata), который добавляет context, `dataFormat` и другие подсказки для перевода).

### `options` [#options]

**Тип** `string | TranslateOptions` · **Обязательно**

Строка целевой локали, например `'es'`, или объект параметров:

```typescript
type TranslateOptions = {
  targetLocale: string; // локаль для перевода
  sourceLocale?: string; // переопределяет sourceLocale экземпляра
  modelProvider?: string; // необязательная подсказка провайдера модели
};
```

### `timeout` [#timeout]

**Тип** `number` · **Необязательно**

Тайм-аут запроса в миллисекундах. Если не указано, используется значение по умолчанию экземпляра.

## Возвращает [#returns]

**Тип** `Promise<TranslationResult>`

Промис завершается значением [`TranslationResult`](/docs/platform/core/reference/types/translation-result) — это размеченное объединение успешного результата (с `translation` и `locale`) и результата с ошибкой (с `error` и `code`). Прежде чем читать перевод, всегда уточняйте тип по `success`.

## Примеры [#examples]

```typescript
// Простой перевод строки (сокращённая запись локали)
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
// С объектом параметров и явно указанной исходной локалью
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```

```typescript
// С метаданными источника (ICU plural + context)
const result = await gt.translate(
  {
    source: '{count, plural, other {{count} items}}',
    metadata: { dataFormat: 'ICU', context: 'Item count display' },
  },
  { targetLocale: 'es' }
);
```

```typescript
// Перевод целого документа Markdown.
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.