# generaltranslation: General Translation Core SDK: translate
URL: https://generaltranslation.com/ru/docs/core/class/methods/translation/translate.mdx
---
title: translate
description: Справка по API метода `translate` в GT
---

## Обзор

Метод `translate` — основная функция перевода в библиотеке GT.
Он переводит содержимое из исходной локали в указанную целевую с помощью сервисов перевода на базе ИИ.

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

const result = await gt.translate('Hello, world!', 'es');
console.log(result); // "¡Hola, mundo!"
```

Метод поддерживает несколько типов содержимого, включая обычный текст, формат сообщений ICU и сообщения в стиле i18next, а также необязательные метаданные для повышения точности перевода.

<Callout>
  **Требуется аутентификация:**
  Для использования метода `translate` в экземпляре GT должны быть настроены и `apiKey` (или `devApiKey`), и `projectId`.
</Callout>

***

## Справочник

### Параметры

<TypeTable
  type={{
  "source": {
    type: 'TranslateManyEntry',
    description: 'Содержимое для перевода. Может быть обычной строкой или объектом с исходным текстом и метаданными.',
    optional: false,
  },
  "options": {
    type: 'string | TranslateOptions',
    description: 'Строка с целевой локалью (сокращённая форма) или объект параметров с targetLocale и другими настройками.',
    optional: false,
  },
  "timeout?": {
    type: 'number',
    description: 'Необязательный тайм-аут запроса в миллисекундах.',
    optional: true,
  }
}}
/>

### TranslateManyEntry

Параметр `source` может быть как обычной строкой, так и объектом:

```typescript
type TranslateManyEntry = string | { source: Content; metadata?: EntryMetadata };
```


### TranslateOptions

Параметр `options` может быть строкой локали (сокращённая форма для `targetLocale`) или объектом:

```typescript
type TranslateOptions = {
  targetLocale: string;
  sourceLocale?: string;
  modelProvider?: string;
};
```

### Описание параметров

| Параметр  | Описание                                                                                                                          |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `source`  | Содержимое для перевода. Обычная строка или объект с `source` (Content) и необязательным `metadata` (EntryMetadata).              |
| `options` | Строка целевой локали (например, `'es'`) или объект параметров с `targetLocale`, необязательным `sourceLocale` и `modelProvider`. |
| `timeout` | Необязательный тайм-аут запроса в миллисекундах.                                                                                  |

### Возвращаемое значение

```typescript
Promise<TranslationResult | TranslationError>
```

* **TranslationResult**: Содержит переведённое содержимое и метаданные
* **TranslationError**: Содержит информацию об ошибке, если перевод завершился неудачей

***


## Поведение

### Определение типа содержимого

Метод автоматически определяет тип содержимого по параметру `source`:

* **Строка**: Обрабатывается как обычный текст или формат сообщений ICU
* **Элементы JSX**: Обрабатываются как JSX-контент в стиле React
* **Объекты**: Обрабатываются как структурированные форматы сообщений

### Определение локали

* Целевая локаль проверяется на соответствие стандарту BCP-47
* Пользовательские сопоставления локалей применяются, если они настроены
* Для API-запросов используются стандартные коды локалей

### Сокращённая форма `options`

Вы можете передать строку в параметр `options` как сокращённую форму для `{ targetLocale: string }`:

```typescript
// Это эквивалентные варианты:
await gt.translate('Hello', 'es');
await gt.translate('Hello', { targetLocale: 'es' });
```

***

## Примеры

### Перевод простой строки

```typescript
const result = await gt.translate('Welcome to our application', 'fr');
```


### С объектом параметров

```typescript
const result = await gt.translate('Welcome to our application', {
  targetLocale: 'fr',
  sourceLocale: 'en',
});
```

### С метаданными источника

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


### С тайм-аутом

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

***


## Примечания

* Переводит указанную строку в целевую локаль и возвращает промис
* Внутри использует `translateMany` с одной записью

## Что дальше

* **[Переводите несколько элементов с помощью translateMany](/docs/core/class/methods/translation/translate-many)**
* **[Узнайте о параметрах EntryMetadata](/docs/core/types/entry-metadata)**
* **[Изучите тип TranslationResult](/docs/core/types/translation-result)**