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.

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.

Reference

Parameters

The translate method has multiple overloads for different content types:

Text Content

JSX Content

ICU Message Format

i18next Format

Parameters Description

Returns

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

Context Enhancement

When custom mapping includes region or script codes for the target locale, they are automatically added to the metadata for improved translation accuracy.

Examples

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

const result = await gt.translate('Welcome to our application', 'fr');
console.log(result); 
// "Bienvenue dans notre application"

Notes

• Translates a given string to a target locale and returns a promise

Next Steps

• Translate multiple items with translateMany
• Learn about EntryMetadata options
• Explore TranslationResult type