# General Translation Platform: uploadSourceFiles URL: https://generaltranslation.com/ja/docs/platform/core/reference/gt-class-methods/translation/upload-source-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: 翻訳をキューに追加する前に、ソースファイルをプロジェクトにアップロードします。uploadSourceFiles の API リファレンス。 翻訳処理のために、ソースファイルを General Translation プラットフォームにアップロードします。通常これは、プロジェクトを設定したり翻訳ジョブをキューに追加したりする前に行う、ファイル翻訳ワークフローの最初のステップです。 ## 概要 [#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 ``` *注記: `uploadSourceFiles` を使用するには、GT インスタンスに `apiKey` (または `devApiKey`) と `projectId` が必要です。* ## 仕組み [#how-it-works] * **ファイルエンコーディング。** テキストコンテンツは安全に送信できるよう、自動的に base64 エンコードされます。バイナリ `LOTTIE` コンテンツは、あらかじめ 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` **型** `{ source: FileUpload }[]` · **必須** アップロードするソースファイルです。各エントリは、`source` キーの下に `FileUpload` を持ちます。 | フィールド | 説明 | 型 | 任意 | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --- | | `content` | 生のテキストコンテンツ、または `LOTTIE` 用のBase64エンコードされたバイナリコンテンツ。 | `string` | いいえ | | `fileName` | 一意のファイル識別子。通常はファイルパスとファイル名を組み合わせたものです。 | `string` | いいえ | | `fileFormat` | ファイルの形式。 | [`FileFormat`](/docs/platform/core/reference/types/file-format) | いいえ | | `transformFormat` | 共通の `FileUpload` 型では受け付けられますが、このメソッドでは送信されません。出力形式は [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) に渡すファイル参照側で指定してください。 | [`FileFormat`](/docs/platform/core/reference/types/file-format) | はい | | `dataFormat` | ファイル内のデータ形式 (`ICU`、`I18NEXT`、`JSX`、`STRING`) 。 | [`DataFormat`](/docs/platform/core/reference/types/data-format) | はい | | `locale` | ソースファイルの内容のロケール。 | `string` | いいえ | | `branchId` | ファイルのアップロード先のブランチです。省略した場合はデフォルトのブランチが使用されます。 | `string` | はい | | `incomingBranchId` | ブランチを考慮した翻訳トラッキングで使用される、取り込み元のブランチ。 | `string` | はい | | `checkedOutBranchId` | ブランチを考慮した翻訳トラッキングで使用される、チェックアウト中のブランチ。 | `string` | はい | | `formatMetadata` | ソースファイルとともに保存される、形式固有のメタデータ。 | `GTJsonFormatMetadata \| FormatMetadata` | はい | | `versionId` | 高度なユースケース向けのバージョン ID。 | `string` | はい | | `fileId` | 高度なユースケース向けのファイル ID。 | `string` | はい | ### `options` **型** `UploadFilesOptions` · **必須** アップロードの設定: | フィールド | 説明 | 型 | 任意 | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --- | | `sourceLocale` | アップロードのソースロケール。プロジェクトのデフォルトロケールと異なる場合は、そちらも更新されます。 | `string` | いいえ | | `modelProvider` | 共有オプション型では受け付けられますが、このアップロードメソッドでは送信されません。代わりに [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) でプロバイダーを設定してください。 | `string` | はい | | `timeout` | リクエストのタイムアウト (ミリ秒) 。 | `number` | はい | *注: `branchId` はアップロードオプションではありません。各ファイルオブジェクトに含まれるファイルごとのフィールドであり、`UploadFilesOptions` の一部ではありません。* ## 戻り値 [#returns] **型** `Promise` アップロードされたファイル参照と要約を含む `UploadFilesResponse` を返します。 ```typescript type UploadFilesResponse = { uploadedFiles: FileReference[]; // 後続の操作で使用する参照 count: number; // 正常にアップロードされたファイル数 message: string; // APIからのステータスメッセージ }; ``` 各 `FileReference` は、次のような形式です： ```typescript type FileReference = { fileId: string; versionId: string; branchId: string; // 現在のAPIでは、デフォルトのブランチの場合これが省略されることがあります fileName: string; fileFormat: FileFormat; transformFormat?: FileFormat; // このアップロードメソッドでは設定されません dataFormat?: DataFormat; }; ``` ライブラリの型定義では `branchId` は必須として宣言されていますが、現在のAPIはデフォルトのブランチを選択する場合にこれを省略することがあります。また、`transformFormat` は設定されません。形式変換が必要な場合は、参照を [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) に渡す前にそのフィールドを設定してください。 ## 例 [#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', 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 エンコードされます。バイナリ `LOTTIE` コンテンツは、Base64 エンコードされた `.lottie` ZIP ファイルとして渡してください。 * ファイル名は一意の識別子にする必要があり、通常はファイルパスを含めます。 * 各ファイルの `locale` フィールドは、`sourceLocale` オプションと一致している必要があります。 * ファイルサイズが大きい場合やファイル数が多い場合は、タイムアウト値を増やす必要があることがあります。 * このメソッドから返される `ファイル参照` は後続の操作に必要で、ブランチ をサポートするバージョン管理用の `branchId` が含まれます。 * **サポートされている形式:** [`FileFormat`](/docs/platform/core/reference/types/file-format)。 ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.