# generaltranslation: General Translation Core SDK: Overview
URL: https://generaltranslation.com/en-US/docs/core.mdx
---
title: Overview
description: Overview of the generaltranslation library
---

## Introduction

The `generaltranslation` library serves as GT's core i18n library housing utility functions and classes for translation and formatting.
It is often used with framework packages like `gt-next` and `gt-react`, but can be used as a standalone library.

import Video from '@/components/Video';

<Video src='https://assets.gtx.dev/core-demo.mp4' />

```typescript title="index.ts"
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.formatNum(29.99, { style: 'currency', currency: '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

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
  ```bash
  npm install generaltranslation
  ```
  </Tab>
  <Tab value="yarn">
  ```bash
  yarn add generaltranslation
  ```
  </Tab>

  <Tab value="bun">
  ```bash
  bun add generaltranslation
  ```
  </Tab>
  <Tab value="pnpm">
  ```bash
  pnpm add generaltranslation
  ```
  </Tab>
</Tabs>

---

## 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`](/docs/core/class/constructor) method for more information.

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

### String translation

Check out the [`translate`](/docs/core/class/methods/translation/translate) method for more information.

```typescript
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`](/docs/core/class/methods/translation/upload-source-files)
and [`queryFileData`](/docs/core/class/methods/translation/query-file-data) methods for more information.

```typescript
// 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](/docs/core/class/constructor)** - Initialize GT instance with configuration
- **[setConfig](/docs/core/class/set-config)** - Update GT instance configuration

#### Translation Methods

- **[translate](/docs/core/class/methods/translation/translate)** - Core translation functionality
- **[translateMany](/docs/core/class/methods/translation/translate-many)** - Batch translation
- **[setupProject](/docs/core/class/methods/translation/setup-project)** - Project initialization
- **[checkJobStatus](/docs/core/class/methods/translation/check-job-status)** - Check job progress
- **[getProjectData](/docs/core/class/methods/translation/get-project-data)** - Retrieve project information
- **[uploadSourceFiles](/docs/core/class/methods/translation/upload-source-files)** - Upload files for translation
- **[uploadTranslations](/docs/core/class/methods/translation/upload-translations)** - Upload pre-existing translations
- **[enqueueFiles](/docs/core/class/methods/translation/enqueue-files)** - Queue files for processing
- **[queryFileData](/docs/core/class/methods/translation/query-file-data)** - Check translation status
- **[downloadFile](/docs/core/class/methods/translation/download-file)** - Download single file
- **[downloadFileBatch](/docs/core/class/methods/translation/download-file-batch)** - Download multiple files
- **[querySourceFile](/docs/core/class/methods/translation/query-source-file)** - Query source file information

#### Formatting Methods

- **[formatMessage](/docs/core/class/methods/formatting/format-message)** - Internationalized text formatting
- **[formatNum](/docs/core/class/methods/formatting/format-num)** - Number formatting
- **[formatDateTime](/docs/core/class/methods/formatting/format-date-time)** - Date and time formatting

#### Locale Methods

- **[getLocaleName](/docs/core/class/methods/locales/get-locale-name)** - Get locale display name
- **[getLocaleProperties](/docs/core/class/methods/locales/get-locale-properties)** - Get comprehensive locale information
- **[getLocaleDirection](/docs/core/class/methods/locales/get-locale-direction)** - Get text direction for locale
- **[getLocaleEmoji](/docs/core/class/methods/locales/get-locale-emoji)** - Get flag emoji for locale
- **[getRegionProperties](/docs/core/class/methods/locales/get-region-properties)** - Get region information and properties
- **[isValidLocale](/docs/core/class/methods/locales/is-valid-locale)** - Validate locale code
- **[resolveAliasLocale](/docs/core/class/methods/locales/resolve-alias-locale)** - Convert canonical locales to aliases
- **[resolveCanonicalLocale](/docs/core/class/methods/locales/resolve-canonical-locale)** - Convert alias locales to canonical form
- **[standardizeLocale](/docs/core/class/methods/locales/standardize-locale)** - Standardize locale code formatting
- **[isSameDialect](/docs/core/class/methods/locales/is-same-dialect)** - Check if locales represent same dialect
- **[isSameLanguage](/docs/core/class/methods/locales/is-same-language)** - Check if locales represent same language
- **[isSupersetLocale](/docs/core/class/methods/locales/is-superset-locale)** - Check locale hierarchy relationships
- **[determineLocale](/docs/core/class/methods/locales/determine-locale)** - Find best matching locale from preferences
- **[requiresTranslation](/docs/core/class/methods/locales/requires-translation)** - Determine if translation is needed

### Utility functions

#### Formatting Functions

- **[formatMessage](/docs/core/functions/formatting/format-message)** - Standalone text formatting
- **[formatNum](/docs/core/functions/formatting/format-num)** - Standalone number formatting
- **[formatDateTime](/docs/core/functions/formatting/format-date-time)** - Standalone date/time formatting

#### Locale Functions

- **[getLocaleName](/docs/core/functions/locales/get-locale-name)** - Standalone locale name utility
- **[getLocaleProperties](/docs/core/functions/locales/get-locale-properties)** - Standalone locale properties
- **[getLocaleDirection](/docs/core/functions/locales/get-locale-direction)** - Standalone text direction utility
- **[getLocaleEmoji](/docs/core/functions/locales/get-locale-emoji)** - Standalone emoji utility
- **[getRegionProperties](/docs/core/functions/locales/get-region-properties)** - Standalone region properties utility
- **[isValidLocale](/docs/core/functions/locales/is-valid-locale)** - Standalone locale validation
- **[resolveAliasLocale](/docs/core/functions/locales/resolve-alias-locale)** - Standalone alias locale resolution
- **[standardizeLocale](/docs/core/functions/locales/standardize-locale)** - Standalone locale standardization
- **[isSameDialect](/docs/core/functions/locales/is-same-dialect)** - Standalone dialect comparison
- **[isSameLanguage](/docs/core/functions/locales/is-same-language)** - Standalone language comparison
- **[isSupersetLocale](/docs/core/functions/locales/is-superset-locale)** - Standalone locale hierarchy checking
- **[determineLocale](/docs/core/functions/locales/determine-locale)** - Standalone locale negotiation
- **[requiresTranslation](/docs/core/functions/locales/requires-translation)** - Standalone translation requirement checking

### Types and Interfaces

TypeScript definitions:

- **[GTConstructorParams](/docs/core/types/gt-constructor-params)** - Configuration options
- **[LocaleProperties](/docs/core/types/locale-properties)** - Comprehensive locale information
- **[TranslationResult](/docs/core/types/translation-result)** - Translation response types
- **[TranslateManyResult](/docs/core/types/translate-many-result)** - Batch translation response
- **[FileToTranslate](/docs/core/types/file-to-translate)** - File translation configuration
- **[EnqueueFilesOptions](/docs/core/types/enqueue-files-options)** - File queuing options
- **[Entry](/docs/core/types/Entry)** - Translation entry structure
- **[EntryMetadata](/docs/core/types/entry-metadata)** - Entry metadata information
- **[Content](/docs/core/types/Content)** - Content type definitions
- **[Variable](/docs/core/types/Variable)** - Variable structure
- **[VariableType](/docs/core/types/variable-type)** - Variable type definitions
- **[JsxElement](/docs/core/types/jsx-element)** - JSX element type
- **[JsxChild](/docs/core/types/jsx-child)** - JSX child type
- **[JsxChildren](/docs/core/types/jsx-children)** - JSX children type
- **[DataFormat](/docs/core/types/data-format)** - Data format specifications
- **[CustomMapping](/docs/core/types/custom-mapping)** - Custom mapping configuration

---

## Next steps

- **[Get started with the GT class](/docs/core/class/constructor)**
- **[Explore translation methods](/docs/core/class/methods/translation/translate)**
- **[Learn about locale utilities](/docs/core/class/methods/locales/get-locale-name)**
- **[Check out formatting options](/docs/core/class/methods/formatting/format-message)**
- **[Browse standalone functions](/docs/core/functions/formatting/format-message)**

For framework-specific usage, see the [Next.js](/docs/next) or [React](/docs/react) documentation.