# generaltranslation: General Translation Core SDK: uploadSourceFiles
URL: https://generaltranslation.com/ja/docs/core/class/methods/translation/upload-source-files.mdx
---
title: uploadSourceFiles
description: 翻訳用のソースファイルをアップロードする `uploadSourceFiles` メソッドの API リファレンス
---

## 概要

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

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

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

<Mermaid
  chart="
graph TD;
A[uploadSourceFiles];
B[setupProject];
C[enqueueFiles];
E[queryFileData];
F[downloadFileBatch];
A --> B;
B --> C;
C --> E;
E --> F;
"
/>


## リファレンス

### パラメータ

| 名前        | 型                          | 説明                  |
| --------- | -------------------------- | ------------------- |
| `files`   | `{ source: FileUpload }[]` | アップロード対象のソースファイルの配列 |
| `options` | `UploadFilesOptions`       | アップロードの設定オプション      |

#### FileUpload の構造

| 名前            | 型            | 説明                                 |
| ------------- | ------------ | ---------------------------------- |
| `content`     | `string`     | ファイルの生の内容を表す文字列                    |
| `fileName`    | `string`     | 一意のファイル識別子 (通常はファイルパス + 名前)        |
| `fileFormat`  | `FileFormat` | ファイル形式 (JSON、MDX、MD、XML など)        |
| `dataFormat?` | `DataFormat` | ファイル内データの形式 (省略可。ICU、I18NEXT、JSX)  |
| `locale`      | `string`     | ソースファイル内容のロケール                     |
| `versionId?`  | `string`     | 高度な用途向けの省略可能なバージョン ID              |
| `fileId?`     | `string`     | 高度な用途向けの省略可能なファイル ID               |

#### UploadFilesOptions

| 名前               | 型        | 説明                          |
| ---------------- | -------- | --------------------------- |
| `sourceLocale`   | `string` | アップロードするすべてのファイルのソースロケール    |
| `branchId?`      | `string` | アップロード先として指定する任意の branch ID |
| `modelProvider?` | `string` | 優先する AI モデルプロバイダ (任意)       |
| `timeout?`       | `number` | リクエストのタイムアウト (ミリ秒)          |

### 戻り値

`Promise<UploadFilesResponse>` - アップロード結果とファイル参照情報が含まれます。

```typescript
type UploadFilesResponse = {
  uploadedFiles: FileReference[];
  count: number;
  message: string;
}
```

| Property        | Type              | 説明                          |
| --------------- | ----------------- | --------------------------- |
| `uploadedFiles` | `FileReference[]` | 後続の操作で使用するアップロード済みファイル参照の配列 |
| `count`         | `number`          | 正常にアップロードされたファイルの数          |
| `message`       | `string`          | API からのステータスメッセージ           |


#### FileReference の構造

```typescript
type FileReference = {
  fileId: string;
  versionId: string;
  branchId: string;
  fileName: string;
  fileFormat: FileFormat;
  dataFormat?: DataFormat;
  locale?: string;
}
```

***


## 使用例

### 基本的な使い方

JSON翻訳ファイルをアップロードします:

```typescript copy
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 copy
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 copy
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(`${files.length} 件のファイルをアップロード中...`);

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

    if (result.count !== files.length) {
      console.warn(`${files.length} 件のファイルを期待しましたが、${result.count} 件のみアップロードされました`);
    }

    return result.uploadedFiles;

  } catch (error) {
    console.error('アップロードに失敗しました:', error);
    throw error;
  }
}

const uploadedFiles = await uploadAllJsonFiles();
```

***


## 注記

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

## 次のステップ

* アップロード済みファイルを翻訳用に準備するには、[`setupProject`](/docs/core/class/methods/translation/setup-project)を参照してください
* 翻訳ジョブを開始するには、[`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files)を参照してください
* 既存の翻訳をアップロードするには、[`uploadTranslations`](/docs/core/class/methods/translation/upload-translations)を参照してください
* ファイル構造の詳細については、`FileUpload`を参照してください