# General Translation Platform: querySourceFile
URL: https://generaltranslation.com/ja/docs/platform/core/reference/gt-class-methods/translation/query-source-file.mdx
---

title: querySourceFile
description: ソースファイルのメタデータと関連する翻訳情報を取得します。querySourceFile の API リファレンス。

---

General Translation で、ソースファイルとそのすべての翻訳に関する詳細な情報を取得します。これには、ファイルのメタデータ、各ロケールでの翻訳ステータス、作成・完了・承認・公開のタイムスタンプが含まれます。

## 概要 [#overview]

ファイルを識別するクエリを指定して `querySourceFile` を呼び出します。戻り値には、ソースファイルのメタデータに加え、各ロケールの翻訳エントリが含まれます。

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

const result = await gt.querySourceFile({
  fileId: 'file-123',
  versionId: 'version-456',
});

console.log(`Source file: ${result.sourceFile.fileName}`);
console.log(`Available in ${result.translations.length} locales`);
```

署名:

```typescript
querySourceFile(
  data: FileQuery,
  options?: CheckFileTranslationsOptions
): Promise<FileQueryResult>
```

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

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

* **翻訳ステータスの全体像。** ソースファイルと、各ターゲットロケールの翻訳ステータスを返します。
* **タイムスタンプのライフサイクル。** 翻訳のタイムスタンプは `createdAt` → `completedAt` → `approvedAt` → `publishedAt` の順に進みます。タイムスタンプが `null` の場合、その段階にはまだ到達していないことを意味します。
* **設定済みのロケール。** ソースファイルの `locales` 配列には、翻訳用に設定されているすべてのターゲットロケールが一覧表示されます。

## パラメーター [#parameters]

| パラメーター                | 説明                    | 型                              | 任意  | デフォルト |
| --------------------- | --------------------- | ------------------------------ | --- | ----- |
| [`data`](#data)       | 取得するファイルを指定するファイルクエリ。 | `FileQuery`                    | いいえ | —     |
| [`options`](#options) | リクエストの設定。             | `CheckFileTranslationsOptions` | はい  | —     |

### `data` [#data]

**型** `FileQuery` · **必須**

照会するファイルを指定します。

| Field       | Description               | Type     | Optional |
| ----------- | ------------------------- | -------- | -------- |
| `fileId`    | 照会するファイルの一意の識別子。          | `string` | いいえ      |
| `versionId` | 特定のファイルバージョンの Version ID。 | `string` | はい       |
| `branchId`  | 特定のブランチの Branch ID。       | `string` | はい       |

### `options` [#options]

**型** `CheckFileTranslationsOptions` · **任意**

| フィールド     | 説明                     | 型        | 任意 |
| --------- | ---------------------- | -------- | -- |
| `timeout` | リクエストのタイムアウト時間 (ミリ秒) 。 | `number` | はい |

## 戻り値 [#returns]

**型** `Promise<FileQueryResult>`

ソースファイル情報とすべてのロケールの翻訳ステータスを含む `FileQueryResult` を返します。

```typescript
type FileQueryResult = {
  sourceFile: {
    id: string;
    fileId: string;
    versionId: string;
    sourceLocale: string;
    fileName: string;
    fileFormat: string;
    dataFormat: string | null;
    createdAt: string;
    updatedAt: string;
    locales: string[];
  };
  translations: {
    locale: string;
    completedAt: string | null;
    approvedAt: string | null;
    publishedAt: string | null;
    createdAt: string | null;
    updatedAt: string | null;
  }[];
};
```

ソースファイルのプロパティ:

| プロパティ          | 説明                              | 型                |
| -------------- | ------------------------------- | ---------------- |
| `id`           | 内部データベース ID。                    | `string`         |
| `fileId`       | 一意のファイル識別子。                     | `string`         |
| `versionId`    | バージョン識別子。                       | `string`         |
| `sourceLocale` | ソース言語のロケール。                     | `string`         |
| `fileName`     | 元のファイル名。                        | `string`         |
| `fileFormat`   | ファイル形式 (JSON、MD、MDX など) 。       | `string`         |
| `dataFormat`   | ファイル内のデータ形式 (ICU、I18NEXT、JSX) 。 | `string \| null` |
| `createdAt`    | ファイル作成日時の ISO タイムスタンプ。          | `string`         |
| `updatedAt`    | 最終更新日時の ISO タイムスタンプ。            | `string`         |
| `locales`      | このファイルのターゲットロケールの一覧。            | `string[]`       |

翻訳のプロパティ:

| プロパティ         | 説明                      | 型                |
| ------------- | ----------------------- | ---------------- |
| `locale`      | ターゲットロケールを表すロケールコード。    | `string`         |
| `completedAt` | 翻訳完了日時の ISO タイムスタンプ。    | `string \| null` |
| `approvedAt`  | 翻訳承認日時の ISO タイムスタンプ。    | `string \| null` |
| `publishedAt` | 翻訳公開日時の ISO タイムスタンプ。    | `string \| null` |
| `createdAt`   | 翻訳ジョブ作成日時の ISO タイムスタンプ。 | `string \| null` |
| `updatedAt`   | 最終翻訳更新日時の ISO タイムスタンプ。  | `string \| null` |

## 例 [#examples]

```typescript title="index.ts"
import { GT } from 'generaltranslation';

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

async function getFileInfo(fileId: string, versionId?: string) {
  const result = await gt.querySourceFile({
    fileId,
    versionId,
  });

  console.log('=== Source File Info ===');
  console.log(`Name: ${result.sourceFile.fileName}`);
  console.log(`Format: ${result.sourceFile.fileFormat}`);
  console.log(`Source Locale: ${result.sourceFile.sourceLocale}`);
  console.log(`Created: ${new Date(result.sourceFile.createdAt).toLocaleString()}`);
  console.log(`Updated: ${new Date(result.sourceFile.updatedAt).toLocaleString()}`);

  console.log('\n=== Translation Status ===');
  result.translations.forEach((translation) => {
    console.log(`${translation.locale}:`);
    console.log(
      `  Created: ${translation.createdAt ? new Date(translation.createdAt).toLocaleString() : 'Not started'}`
    );
    console.log(
      `  Completed: ${translation.completedAt ? new Date(translation.completedAt).toLocaleString() : 'In progress'}`
    );
    console.log(
      `  Published: ${translation.publishedAt ? new Date(translation.publishedAt).toLocaleString() : 'Not published'}`
    );
  });

  return result;
}

const fileInfo = await getFileInfo('file-123', 'version-456');
```

## メモ [#notes]

* すべてのターゲットロケールについて、ソースファイルと翻訳のステータスを返します。
* 翻訳のタイムスタンプは `createdAt` → `completedAt` → `approvedAt` → `publishedAt` のライフサイクルに従います。タイムスタンプが `null` の場合は、その段階にまだ到達していないことを示します。
* ソースファイルの `locales` 配列には、翻訳用に設定されているすべてのターゲットロケールが表示されます。
* 詳細なレポート作成、進捗管理、ファイル管理ワークフローには、このメソッドを使用します。