# generaltranslation: General Translation Core SDK: translate
URL: https://generaltranslation.com/en-US/docs/core/class/methods/translation/translate.mdx
---
title: translate
description: API reference for the GT translate method
---

## Overview

The `translate` method is the primary translation function in the GT library.
It translates content from the source locale to a specified target locale using AI-powered translation services.

```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!"
```

The method supports multiple content types including plain text, ICU message format, and i18next-style messages, with optional metadata for improved translation accuracy.

<Callout>
**Authentication Required:**
The `translate` method requires both `apiKey` (or `devApiKey`) and `projectId` to be configured in the GT instance.
</Callout>

---

## Reference

### Parameters

<TypeTable
  type={{
    "source": {
      type: 'TranslateManyEntry',
      description: 'The content to translate. Can be a plain string or an object with source and metadata.',
      optional: false,
    },
    "options": {
      type: 'string | TranslateOptions',
      description: 'Target locale string (shorthand) or an options object with targetLocale and other settings.',
      optional: false,
    },
    "timeout?": {
      type: 'number',
      description: 'Optional request timeout in milliseconds.',
      optional: true,
    }
  }}
/>

### TranslateManyEntry

The `source` parameter accepts either a plain string or an object:

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

### TranslateOptions

The `options` parameter can be a locale string (shorthand for `targetLocale`) or an object:

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

### Parameters description

| Parameter | Description |
|-----------|-------------|
| `source` | The content to translate. A plain string or an object with `source` (Content) and optional `metadata` (EntryMetadata). |
| `options` | A target locale string (e.g., `'es'`) or an options object with `targetLocale`, optional `sourceLocale`, and `modelProvider`. |
| `timeout` | Optional request timeout in milliseconds. |

### Returns

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

- **TranslationResult**: Contains the translated content and metadata
- **TranslationError**: Contains error information if translation fails

---

## Behavior

### Content type detection

The method automatically detects content type based on the `source` parameter:

- **String**: Treated as plain text or ICU message format
- **JSX Elements**: Handled as React-style JSX content  
- **Objects**: Processed as structured message formats

### Locale resolution

- Target locale is validated against BCP-47 standards
- Custom locale mappings are applied if configured
- Canonical locale codes are used for API requests

### Options shorthand

You can pass a string as the `options` parameter as a shorthand for `{ targetLocale: string }`:

```typescript
// These are equivalent:
await gt.translate('Hello', 'es');
await gt.translate('Hello', { targetLocale: 'es' });
```

---

## Examples

### Simple string translation

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

### With options object

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

### With source metadata

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

### With timeout

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

---

## Notes

- Translates a given string to a target locale and returns a promise
- Uses `translateMany` under the hood with a single entry

## Next steps

- **[Translate multiple items with translateMany](/docs/core/class/methods/translation/translate-many)**
- **[Learn about EntryMetadata options](/docs/core/types/entry-metadata)**
- **[Explore TranslationResult type](/docs/core/types/translation-result)**