# 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: FileReference[],
  options?: SetupProjectOptions
): Promise<SetupProjectResult>
```

*Note: `setupProject` requires an `apiKey` (or `devApiKey`) and `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. | `FileReference[]`     | No       | —       |
| [`options`](#options) | Settings for the setup job.                            | `SetupProjectOptions` | Yes      | —       |

### `files` [#files]

**Type** `FileReference[]` · **Required**

The file references returned by [`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files):

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
  fileName: string;
  fileFormat: FileFormat;
  transformFormat?: FileFormat; // output format requested for generated translations
  dataFormat?: DataFormat;
};
```

Both `fileName` and `fileFormat` are required on `FileReference`; `transformFormat` and `dataFormat` are optional.

### `options` [#options]

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

| Field       | Description                                                     | Type       | Optional |
| ----------- | --------------------------------------------------------------- | ---------- | -------- |
| `force`     | Force setup again by invalidating existing cached translations. | `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',
    fileName: 'app.json',
    fileFormat: 'JSON',
  },
  {
    fileId: 'file-789',
    versionId: 'version-012',
    branchId: 'branch-789',
    fileName: 'content.md',
    fileFormat: 'MD',
  },
];

const setupResult = await gt.setupProject(fileRefs);

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

  // Monitor job status (checkJobStatus returns a flat array)
  const jobStatus = await gt.checkJobStatus([setupResult.setupJobId]);
  console.log(`Job status: ${jobStatus[0].status}`);
} 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.