# General Translation Platform: Quickstart
URL: https://generaltranslation.com/en-US/docs/platform/core/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Use the General Translation Core library when you need lower-level control, and translate your first string.

The `generaltranslation` library is General Translation's Core i18n library for translation, formatting, and locale utilities.

Most framework apps should start with [gt-react or gt-next](/docs/react/overview). Use `generaltranslation` directly when you want lower-level control, a custom workflow, or translation utilities outside a framework integration.

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

## What `generaltranslation` does [#what-it-does]

`generaltranslation` gives you direct access to:

- **String translation** for translating strings or structured content from code.
- **File translation** for uploading source files, queueing translation jobs, checking status, and downloading translated output.
- **Locale utilities** for validating, comparing, resolving, and displaying locale codes.
- **Formatting utilities** for locale-aware numbers, dates, messages, lists, and relative time.

## When to use `generaltranslation` [#when-to-use]

Use `generaltranslation` when you need to:

- Translate content from a script, backend service, worker, or custom build step.
- Upload and download translation files without using the CLI.
- Build custom translation automation around project files, jobs, branches, or tags.
- Format numbers, dates, messages, or locale names outside React or Next.js.
- Share GT behavior across packages that do not use the same frontend framework.

## Quickstart [#quickstart]
Install `generaltranslation`, create a [GT](/docs/platform/core/reference/gt-class/constructor) instance with your project ID and API key, and translate your first string.

### 1. Install `generaltranslation`

<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>

### 2. Get an API key

Create a `GT_PROJECT_ID` and `GT_API_KEY` in the Dashboard. Open the [API Keys page](https://dash.generaltranslation.com/api-keys), click **Create API Key**, enter a name, and confirm.

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=your-api-key
```

General Translation offers high free rate limits for personal projects, solo developers, and the community.

### 3. Initialize the GT class

Initialize the [GT](/docs/platform/core/reference/gt-class/constructor) class and securely pass your `GT_PROJECT_ID` and `GT_API_KEY`.

```typescript title="src/index.ts"
import { GT } from 'generaltranslation';

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

You can configure default locales on the [GT](/docs/platform/core/reference/gt-class/constructor) instance. Use default locales when most calls use the same source or target locale.

```typescript title="src/index.ts"
const gt = new GT({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  sourceLocale: 'en',
  targetLocale: 'es',
});
```

(See [GT class](/docs/platform/core/reference/gt-class/constructor) for all constructor options).

### 4. Translate your first string

Call the [translate](/docs/platform/core/reference/gt-class-methods/translation/translate) method to translate your first string. Pass the string you want to translate and the target locale.

```typescript title="src/index.ts"
const result = await gt.translate('Hello, world!', 'es');

if (result.success) {
  console.log(result.translation); // "¡Hola, mundo!"
} else {
  console.error(`Translation failed: ${result.error}`);
}
```

Translation methods require an API key and project ID. Formatting and locale utilities can be used without translation API access.

## Next steps

- /docs/platform/core/guides/translating-strings
- /docs/platform/core/guides/translating-files
- /docs/platform/core/guides/locale-codes

## Sitemap

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