# General Translation Platform: uploadSourceFiles
URL: https://generaltranslation.com/ja/docs/platform/core/reference/gt-class-methods/translation/upload-source-files.mdx
---

title: uploadSourceFiles
description: 翻訳をキューに追加する前に、ソースファイルを Project にアップロードします。uploadSourceFiles の API リファレンス。

---

翻訳処理のために、ソースファイルを General Translation プラットフォームにアップロードします。通常これは、Project を設定したり翻訳ジョブをキューに追加したりする前に行う、ファイル翻訳ワークフローの最初のステップです。

## 概要 [#overview]

`uploadSourceFiles` を、ファイルの配列とソースロケールを設定するオプションオブジェクトを指定して呼び出します。戻り値は、後続の手順で使用するアップロード済みのファイル参照です。

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

const result = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
});
```

シグネチャ:

```typescript
uploadSourceFiles(
  files: { source: FileUpload }[],
  options: UploadFilesOptions
): Promise<UploadFilesResponse>
```

*注記: `uploadSourceFiles` を使用するには、GT インスタンスに `apiKey` (または `devApiKey`) と `projectId` が必要です。*

## 仕組み [#how-it-works]

* **ファイルエンコーディング。** 安全に送信できるよう、ファイルの内容は自動的に Base64 エンコードされます。
* **ファイル参照。** 返されるファイル参照 (`fileId`、`versionId`、`branchId` を含む) は、後続の操作で必要になります。
* **一般的なワークフロー。** `uploadSourceFiles` はファイルパイプラインのエントリポイントです。ソースファイルをアップロードした後、[`setupProject`](/docs/platform/core/reference/gt-class-methods/translation/setup-project) → [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) → [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) → [`downloadFileBatch`](/docs/platform/core/reference/gt-class-methods/translation/download-file-batch) の順に進みます。

## パラメータ [#parameters]

| パラメータ                 | 説明                  | 型                          | 任意  | デフォルト |
| --------------------- | ------------------- | -------------------------- | --- | ----- |
| [`files`](#files)     | アップロードするソースファイルの配列。 | `{ source: FileUpload }[]` | いいえ | —     |
| [`options`](#options) | アップロードの設定オプション。     | `UploadFilesOptions`       | いいえ | —     |

### `files` [#files]

**型** `{ source: FileUpload }[]` · **必須**

アップロードするソースファイルです。各エントリは、`source` キーの下に `FileUpload` を持ちます。

| フィールド             | 説明                                                                                                         | 型                                                               | 任意  |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --- |
| `content`         | 生のファイル内容を表す文字列。                                                                                            | `string`                                                        | いいえ |
| `fileName`        | 一意のファイル識別子。通常はファイルパスとファイル名を組み合わせたものです。                                                                     | `string`                                                        | いいえ |
| `fileFormat`      | ファイルの形式。`GTJSON`、`JSON`、`PO`、`POT`、`YAML`、`MDX`、`MD`、`TS`、`JS`、`HTML`、`TXT`、`TWILIO_CONTENT_JSON` のいずれかです。 | `FileFormat`                                                    | いいえ |
| `transformFormat` | 生成される翻訳に対して要求する出力形式。                                                                                       | `FileFormat`                                                    | はい  |
| `dataFormat`      | ファイル内のデータ形式 (ICU、I18NEXT、JSX) 。                                                                            | [`DataFormat`](/docs/platform/core/reference/types/data-format) | はい  |
| `locale`          | ソースファイルの内容のロケール。                                                                                           | `string`                                                        | いいえ |
| `branchId`        | ファイルのアップロード先のブランチです。省略した場合はデフォルトブランチが使用されます。                                                               | `string`                                                        | はい  |
| `versionId`       | 高度なユースケース向けのバージョン ID。                                                                                      | `string`                                                        | はい  |
| `fileId`          | 高度なユースケース向けのファイル ID。                                                                                       | `string`                                                        | はい  |

### `options` [#options]

**Type** `UploadFilesOptions` · **必須**

アップロードの設定:

| Field           | Description               | Type     | Optional |
| --------------- | ------------------------- | -------- | -------- |
| `sourceLocale`  | アップロードするすべてのファイルのソースロケール。 | `string` | いいえ      |
| `modelProvider` | AIモデルプロバイダーの優先設定。         | `string` | はい       |
| `timeout`       | リクエストのタイムアウト (ミリ秒) 。      | `number` | はい       |

*注: `branchId` はアップロードオプションではありません。各ファイルオブジェクトに含まれるファイルごとのフィールドであり、`UploadFilesOptions` の一部ではありません。*

## 戻り値 [#returns]

**型** `Promise<UploadFilesResponse>`

アップロードされたファイル参照と要約を含む `UploadFilesResponse` を返します。

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[]; // 後続の操作で使用する参照
  count: number; // 正常にアップロードされたファイル数
  message: string; // APIからのステータスメッセージ
};
```

各 `FileReference` は、次のような形式です：

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
  fileName: string;
  fileFormat: FileFormat;
  transformFormat?: FileFormat; // 生成された翻訳に対してリクエストされた出力形式
  dataFormat?: DataFormat;
};
```

## 例 [#examples]

```typescript
// 基本的な使い方：JSON翻訳ファイルをアップロードする
import { GT } from 'generaltranslation';
import fs from 'fs';

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

const files = [
  {
    source: {
      content: fs.readFileSync('./locales/en/common.json', 'utf8'),
      fileName: 'common.json',
      fileFormat: 'JSON' as const,
      locale: 'en',
    },
  },
  {
    source: {
      content: fs.readFileSync('./locales/en/navigation.json', 'utf8'),
      fileName: 'navigation.json',
      fileFormat: 'JSON' as const,
      locale: 'en',
    },
  },
];

const result = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
});

console.log(`Uploaded ${result.count} files`);
result.uploadedFiles.forEach((file) => {
  console.log(`  ${file.fileName}: ${file.fileId} (branch: ${file.branchId})`);
});
```

```typescript
// データ形式を明示的に指定する場合
const files = [
  {
    source: {
      content: '{"welcome": "Welcome, {name}!"}',
      fileName: 'messages.json',
      fileFormat: 'JSON' as const,
      dataFormat: 'ICU' as const, // ICU メッセージフォーマット
      locale: 'en',
    },
  },
  {
    source: {
      content: '{"greeting": "Hello {{name}}"}',
      fileName: 'i18next.json',
      fileFormat: 'JSON' as const,
      dataFormat: 'I18NEXT' as const,
      locale: 'en',
    },
  },
];

const result = await gt.uploadSourceFiles(files, {
  sourceLocale: 'en',
  modelProvider: 'gpt-4',
  timeout: 30000,
});
```

```typescript
// バッチアップロード（エラーハンドリング付き）
import { glob } from 'glob';
import path from 'path';

async function uploadAllJsonFiles() {
  try {
    // すべてのJSONファイルを検索
    const jsonPaths = await glob('./locales/en/**/*.json');

    const files = jsonPaths.map((filePath) => ({
      source: {
        content: fs.readFileSync(filePath, 'utf8'),
        fileName: path.relative('./locales/en', filePath),
        fileFormat: 'JSON' as const,
        locale: 'en',
      },
    }));

    console.log(`Uploading ${files.length} files...`);

    const result = await gt.uploadSourceFiles(files, {
      sourceLocale: 'en',
      timeout: 60000, // 大容量アップロード用の60秒タイムアウト
    });

    if (result.count !== files.length) {
      console.warn(`Expected ${files.length} files, but only ${result.count} uploaded`);
    }

    return result.uploadedFiles;
  } catch (error) {
    console.error('Upload failed:', error);
    throw error;
  }
}

const uploadedFiles = await uploadAllJsonFiles();
```

## メモ [#notes]

* 安全に送信できるよう、ファイルの内容は自動的に Base64 エンコードされます。
* ファイル名は一意の識別子にする必要があり、通常はファイルパスを含めます。
* 各ファイルの `locale` フィールドは、`sourceLocale` オプションと一致している必要があります。
* ファイルサイズが大きい場合やファイル数が多い場合は、タイムアウト値を増やす必要があることがあります。
* このメソッドから返される `ファイル参照` は後続の操作に必要で、ブランチ をサポートするバージョン管理用の `branchId` が含まれます。
* サポートされているファイル形式は `GTJSON`、`JSON`、`PO`、`POT`、`YAML`、`MDX`、`MD`、`TS`、`JS`、`HTML`、`TXT`、`TWILIO_CONTENT_JSON` です。完全な一覧については、`FileFormat` 型を参照してください。