# General Translation Platform: setupProject
URL: https://generaltranslation.com/en-US/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.

Initializes the setup process for a translation project using previously uploaded files with General Translation. It creates an asynchronous setup job that analyzes 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 analyzes file content and structure to optimize 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 enqueueing 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 is already 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 was already 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 analyzes file content and structure to optimize 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 enqueueing 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.