Introduction

The generaltranslation library serves as GT's core i18n library housing utility functions and classes for translation and formatting. It is most oftenly used with framework packages like gt-next and gt-react, but can 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, currencies
const formattedPrice = gt.formatCurrency(29.99, 'USD');
const formattedDate = gt.formatDateTime(new Date());
// "$29.99"
// "9/25/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 major types of translation: string translation and file translation.

Setup

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

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

String Translation

Check out 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 launch a job by uploading a file. Uploading many files will launch many jobs.

Check out 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 - Initialize GT instance with configuration
• setConfig - Update GT instance configuration

Translation Methods

• translate - Core translation functionality
• translateMany - Batch translation
• setupProject - Project initialization
• shouldSetupProject - Check if 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 single translated file
• downloadFileBatch - Download multiple translated files
• querySourceFile - Query source file information

Formatting Methods

• formatMessage - Internationalized 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 locale
• getLocaleEmoji - Get flag emoji for locale
• getRegionProperties - Get region information and properties
• isValidLocale - Validate locale code
• resolveAliasLocale - Convert canonical locales to aliases
• resolveCanonicalLocale - Convert alias locales to canonical form
• standardizeLocale - Standardize locale code formatting
• isSameDialect - Check if locales represent same dialect
• isSameLanguage - Check if locales represent same language
• isSupersetLocale - Check locale hierarchy relationships
• determineLocale - Find best matching locale from preferences
• requiresTranslation - Determine if 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 standardization
• 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 information
• TranslationResult - Translation response types
• TranslateManyResult - Batch translation response
• FileToTranslate - File translation configuration
• EnqueueFilesOptions - File queuing options
• Entry - Translation entry structure
• EntryMetadata - Entry metadata information
• 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
• Check out formatting options
• Browse standalone functions

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