# General Translation Platform: setupProject
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/gt-class-methods/translation/setup-project.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Prepare uploaded files for project translation workflows. API reference for setupProject.

Initialises the setup process for a translation project using previously uploaded files with General Translation. It creates an asynchronous setup job that analyses the files and prepares them for translation workflows.

## Overview [#overview]

Call `setupProject` with the file references from [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files), optionally with setup options. It either queues a setup job (returning a `setupJobId`) or reports that the project is already set up.

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

const setupResult = await gt.setupProject(fileRefs, { timeoutMs: 30000 });
if (setupResult.status === 'queued') {
  console.log(`Setup job created: ${setupResult.setupJobId}`);
} else {
  console.log('Project is already set up');
}
```

Signature:

```typescript
setupProject(
  files: SetupProjectFileReference[],
  options?: SetupProjectOptions
): Promise<SetupProjectResult>
```

*Note: `setupProject` requires an API key (including the deprecated `devApiKey` alias), plus `projectId` on the GT instance. You must upload the files with [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) first.*

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

* **File analysis.** Setup analyses file content and structure to optimise translation workflows.
* **Asynchronous job.** The setup job runs asynchronously — monitor progress with [`checkJobStatus`](/docs/platform/core/reference/gt-class-methods/translation/check-job-status).
* **When required.** Setup is typically required before queueing translation jobs for new projects.
* **Versioning.** File references include `branchId` for versioning with branch support.

## Parameters [#parameters]

| Parameter             | Description                                            | Type                          | Optional | Default |
| --------------------- | ------------------------------------------------------ | ----------------------------- | -------- | ------- |
| [`files`](#files)     | File references from previously uploaded source files. | `SetupProjectFileReference[]` | No       | —       |
| [`options`](#options) | Settings for the setup job.                            | `SetupProjectOptions`         | Yes      | —       |

### `files` [#files]

**Type** `SetupProjectFileReference[]` · **Required**

Import `SetupProjectFileReference` from `generaltranslation/types`. Pass the IDs returned by [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files):

```typescript
type SetupProjectFileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
};
```

All three IDs are required. File names and formats are not sent.

### `options` [#options]

**Type** `SetupProjectOptions` · **Optional**

| Field       | Description                                                                            | Type       | Optional |
| ----------- | -------------------------------------------------------------------------------------- | ---------- | -------- |
| `force`     | Force project context generation; this is not a translation-cache invalidation option. | `boolean`  | Yes      |
| `locales`   | Target locales for the project.                                                        | `string[]` | Yes      |
| `timeoutMs` | Timeout in milliseconds for the API request.                                           | `number`   | Yes      |

## Returns [#returns]

**Type** `Promise<SetupProjectResult>`

Resolves to a `SetupProjectResult`, a union of two variants:

```typescript
type SetupProjectResult =
  | { setupJobId: string; status: 'queued' }
  | { status: 'completed' };
```

* When a setup job is created, it returns the `queued` variant with a `setupJobId`.
* When the project has already been set up, it returns the `completed` variant with no job identifier.

| Property     | Description                                                                                         | Type                      |
| ------------ | --------------------------------------------------------------------------------------------------- | ------------------------- |
| `setupJobId` | Unique identifier for the queued setup job. Present only on the `queued` variant.                   | `string`                  |
| `status`     | `'queued'` when a setup job was created, or `'completed'` when the project had already been set up. | `'queued' \| 'completed'` |

## Examples [#examples]

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

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

// File references from a previous upload
const fileRefs = [
  {
    fileId: 'file-123',
    versionId: 'version-456',
    branchId: 'branch-789',
  },
  {
    fileId: 'file-789',
    versionId: 'version-012',
    branchId: 'branch-789',
  },
];

const setupResult = await gt.setupProject(fileRefs);

if (setupResult.status === 'queued') {
  console.log(`Setup initiated with job ID: ${setupResult.setupJobId}`);

  // Wait for setup with a bounded deadline.
  const result = await gt.awaitJobs([setupResult.setupJobId], { timeoutSeconds: 300 });
  if (!result.complete || result.jobs.some((job) => job.status !== 'completed')) {
    throw new Error('Project setup did not complete successfully');
  }
} else {
  console.log('Project is already set up — no setup job needed');
}
```

## Notes [#notes]

* Files must be uploaded with [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) before calling `setupProject`.
* Project setup analyses file content and structure to optimise translation workflows.
* The setup job runs asynchronously — monitor progress with [`checkJobStatus`](/docs/platform/core/reference/gt-class-methods/translation/check-job-status).
* Setup is typically required before queueing translation jobs for new projects.
* File references include `branchId` for versioning with branch support.

## Sitemap

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