# General Translation Platform: Constructor
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/gt-class/constructor.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Initialize a GT instance with API keys, project settings, default locales, and locale mappings. API reference for Constructor.

Creates a new `GT` instance, the entry point to all General Translation translation, formatting, and locale functionality. Call it once and reuse the instance across your application.

## Overview [#overview]

Construct a `GT` instance with an optional configuration object. Any credentials and locales you set here become the defaults for every method call on the instance.

```typescript
import { GT } from 'generaltranslation';

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

Signature:

```typescript
new GT(params?: GTConstructorParams): GT
```

*Note: You can omit `apiKey`, `devApiKey`, and `projectId` — the constructor reads them from the `GT_API_KEY`, `GT_DEV_API_KEY`, and `GT_PROJECT_ID` environment variables when they are set.*

## How it works [#how-it-works]

- **Environment fallback.** When `apiKey`, `devApiKey`, or `projectId` are not passed, the constructor looks them up in the `GT_API_KEY`, `GT_DEV_API_KEY`, and `GT_PROJECT_ID` environment variables.
- **Configured identities.** Use standard codes such as `en-US`; configured codes are kept as written. To accept another spelling, such as `en-us`, map it with [`customMapping`](/docs/platform/core/reference/types/custom-mapping): `{ 'en-us': { code: 'en-US' } }`. `sourceLocale`, `targetLocale`, and every entry in `locales` validate against the effective mapping, including custom aliases. Invalid codes throw.
- **Returned locale codes.** Project and file responses use your configured spellings and aliases where possible. If multiple configured codes identify the same locale, the first match is used unless your request distinguishes them. Other dialects are not substituted. Runtime translation results use the API's locale codes.
- **Custom mapping precedence.** A [`customMapping`](/docs/platform/core/reference/types/custom-mapping) lets you define locale aliases, override the standard BCP 47 validation, and override the standard locale properties (name, emoji, and so on). Custom mappings take precedence over the standard BCP 47 data.

## Parameters [#parameters]

The constructor accepts a single optional [`GTConstructorParams`](/docs/platform/core/reference/types/gt-constructor-params) object (defaults to `{}`) with the following properties:

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`apiKey`](#api-key) | Project API key for the translation service. | `string` | Yes | `GT_API_KEY` env |
| [`devApiKey`](#dev-api-key) | Alternate project API key, used when `apiKey` is unset. | `string` | Yes | `GT_DEV_API_KEY` env |
| [`projectId`](#project-id) | Unique project identifier. | `string` | Yes | `GT_PROJECT_ID` env |
| [`sourceLocale`](#source-locale) | Default source locale for translations. | `string` | Yes | — |
| [`targetLocale`](#target-locale) | Default target locale for translations. | `string` | Yes | — |
| [`locales`](#locales) | Supported locale codes. | `string[]` | Yes | — |
| [`baseUrl`](#base-url) | API base URL. | `string` | Yes | `https://api.gtx.dev` |
| [`customMapping`](#custom-mapping) | Custom locale code mappings and property overrides. | [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) | Yes | — |

### `apiKey` [#api-key]

**Type** `string` · **Optional** · **Default** `GT_API_KEY` env

Project API key for the translation service. Read from `GT_API_KEY` when not provided. API operations require an API key (including the deprecated `devApiKey` alias), plus a project ID and permission for the operation.

### `devApiKey` [#dev-api-key]

**Type** `string` · **Optional** · **Default** `GT_DEV_API_KEY` env

Deprecated compatibility alias for `apiKey`, not a separate environment-specific key type. Used when `apiKey` is unset. Read from `GT_DEV_API_KEY` when not provided.

### `projectId` [#project-id]

**Type** `string` · **Optional** · **Default** `GT_PROJECT_ID` env

Unique project identifier. Read from `GT_PROJECT_ID` when not provided. API operations require this ID in addition to credentials.

### `sourceLocale` [#source-locale]

**Type** `string` · **Optional**

Default source locale for translations, such as `en`. Its configured spelling is preserved and validated with any `customMapping`, so custom aliases are accepted.

### `targetLocale` [#target-locale]

**Type** `string` · **Optional**

Default target locale for translations, such as `es`. Its configured spelling is preserved and validated with any `customMapping`, so custom aliases are accepted.

### `locales` [#locales]

**Type** `string[]` · **Optional**

Array of supported locale identities. Each code is preserved and validated with the effective `customMapping`; custom aliases are accepted here too.

### `baseUrl` [#base-url]

**Type** `string` · **Optional** · **Default** `https://api.gtx.dev`

API base URL. Override it only when your deployment uses a different endpoint.

### `customMapping` [#custom-mapping]

**Type** [`CustomMapping`](/docs/platform/core/reference/types/custom-mapping) · **Optional**

Custom locale code mappings and property overrides. Use it to (1) define aliases for locale codes, (2) override the standard BCP 47 validation, and (3) override the standard BCP 47 locale properties such as name and emoji.

## Returns [#returns]

**Type** `GT`

A new `GT` instance with all translation, formatting, and locale methods available.

## Examples [#examples]

```typescript
import { GT } from 'generaltranslation';

// Minimal setup — reads credentials from environment variables
const gt = new GT();
```

```typescript
// With API credentials
const gt = new GT({
  projectId: 'my-project-id',
  apiKey: 'my-api-key',
  targetLocale: 'fr',
});
```

```typescript
// With a custom locale alias: use `cn` as an alias for `zh`.
// The General Translation API does not support `cn`, so a custom mapping is required.
const gt = new GT({
  projectId: 'my-project-id',
  apiKey: 'my-api-key',
  targetLocale: 'es',
  customMapping: {
    cn: { code: 'zh' },
  },
});
```

```typescript
// Custom mappings can also override names, emojis, and other locale properties
const gt = new GT({
  projectId: 'my-project-id',
  apiKey: 'my-api-key',
  targetLocale: 'es',
  customMapping: { 'en-US': { name: 'Mandarin', emoji: '🇫🇷' } },
});
```

## Notes [#notes]

- All parameters are optional, but API operations require an API key and `projectId`.
- Configured locale spellings and aliases are preserved; returned codes follow the rules above.
- All locale fields validate against the effective custom mapping.
- Custom mappings take precedence over standard BCP 47 validation and properties.
- Use [`setConfig`](/docs/platform/core/reference/gt-class/set-config) to reconfigure an instance, not direct property assignment.

*Note: `GT` extends [`GTRuntime`](/docs/platform/core/reference/runtime), which supplies runtime translation, formatting, and locales. File/project management remains on `GT`.*

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.