Introduction

The generaltranslation library serves as GT’s core i18n library, providing utility functions and classes for translation and formatting. It is most commonly used with framework packages such as gt-next and gt-react, but it can also be used as a standalone library.

import { GT } from 'generaltranslation';

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

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

// Format numbers, dates, and currencies
const formattedPrice = gt.formatCurrency(29.99, 'USD');
const formattedDate = gt.formatDateTime(new Date());
// "$29.99"
// "25/09/2025"

// Work with locales
const localeProps = gt.getLocaleProperties('fr-CA');
const isValid = gt.isValidLocale('de');
// { language: "fr", region: "CA", ... }
// true

Installation

npm install generaltranslation

yarn add generaltranslation

bun add generaltranslation

pnpm add generaltranslation

Examples

There are two main types of translation: string translation and file translation.

Setup

To enable translation, you need to provide a project ID and API key. See the constructor method for more information.

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

String Translation

See the translate method for more information.

try {
  const result = await gt.translate('Hello, world!');
  console.log(result); // "¡Hola, mundo!"
} catch (error) {
  console.error('Translation failed:', error.message);
}

File Translation

Files are translated as jobs. You start a job by uploading a file. Uploading multiple files will start multiple jobs.

See the uploadSourceFiles and checkFileTranslations methods for more information.

// Files to upload
const files = [
  {
    source: {
      fileName: 'src/components/Button.tsx',
      fileFormat: 'TSX',
      locale: 'en',
      content: '...',
    },
  },
];

// Upload source files
await gt.uploadSourceFiles(files);

Table of contents

GT Class

Main class for translation and locale functionality:

• Constructor - Initialise the GT instance with configuration
• setConfig - Update the GT instance configuration

Translation Methods

• translate - Core translation functionality
• translateMany - Batch translation
• setupProject - Project initialisation
• shouldSetupProject - Check whether project setup is needed
• checkSetupStatus - Verify project setup
• getProjectData - Retrieve project information
• uploadSourceFiles - Upload files for translation
• enqueueFiles - Queue files for processing
• checkFileTranslations - Check translation status
• downloadTranslatedFile - Download a single translated file
• downloadFileBatch - Download multiple translated files
• querySourceFile - Query source file information

Formatting Methods

• formatMessage - Internationalised text formatting
• formatNum - Number formatting
• formatDateTime - Date and time formatting

Locale Methods

• getLocaleName - Get locale display name
• getLocaleProperties - Get comprehensive locale information
• getLocaleDirection - Get text direction for a locale
• getLocaleEmoji - Get the flag emoji for a locale
• getRegionProperties - Get region information and properties
• isValidLocale - Validate a locale code
• resolveAliasLocale - Convert canonical locales to aliases
• resolveCanonicalLocale - Convert alias locales to canonical form
• standardizeLocale - Standardise locale code formatting
• isSameDialect - Check whether locales represent the same dialect
• isSameLanguage - Check whether locales represent the same language
• isSupersetLocale - Check locale hierarchy relationships
• determineLocale - Find the best matching locale from preferences
• requiresTranslation - Determine whether translation is needed

Utility functions

Formatting functions

• formatMessage - Standalone text formatting
• formatNum - Standalone number formatting
• formatDateTime - Standalone date/time formatting

Locale Functions

• getLocaleName - Standalone locale name utility
• getLocaleProperties - Standalone locale properties
• getLocaleDirection - Standalone text direction utility
• getLocaleEmoji - Standalone emoji utility
• getRegionProperties - Standalone region properties utility
• isValidLocale - Standalone locale validation
• resolveAliasLocale - Standalone alias locale resolution
• standardizeLocale - Standalone locale standardisation
• isSameDialect - Standalone dialect comparison
• isSameLanguage - Standalone language comparison
• isSupersetLocale - Standalone locale hierarchy checking
• determineLocale - Standalone locale negotiation
• requiresTranslation - Standalone translation requirement checking

Types and Interfaces

TypeScript definitions:

• GTConstructorParams - Configuration options
• LocaleProperties - Comprehensive locale details
• TranslationResult - Translation response types
• TranslateManyResult - Batch translation response
• FileToTranslate - File translation configuration
• EnqueueFilesOptions - File queueing options
• Entry - Translation entry structure
• EntryMetadata - Entry metadata
• Content - Content type definitions
• Variable - Variable structure
• VariableType - Variable type definitions
• JsxElement - JSX element type
• JsxChild - JSX child type
• JsxChildren - JSX children type
• DataFormat - Data format specifications
• CustomMapping - Custom mapping configuration

Next steps

• Get started with the GT class
• Explore translation methods
• Learn about locale utilities
• Explore formatting options
• Browse standalone functions

For framework-specific usage, see the Next.js or React documentation.