# General Translation Platform: ファイルの翻訳
URL: https://generaltranslation.com/ja/docs/platform/core/guides/translating-files.mdx
---

title: ファイルの翻訳
description: "`generaltranslation` ライブラリでファイルを翻訳する方法: このガイドでは、ソースファイルのアップロード、翻訳のエンキュー、ステータスの確認、翻訳済みファイルのダウンロードについて説明します。"
related:
  links:
    - /docs/platform/core/guides/translating-strings
    - /docs/platform/core/guides/locale-codes

---

`generaltranslation` ライブラリでは、ソースファイル全体を翻訳できます。このページでは、ファイルのアップロード、エンキュー、ステータス確認、ダウンロードのワークフローについて説明します。

## 始める前に [#before-start]

[Quickstart](/docs/platform/core/quickstart) を完了し、`generaltranslation` のインストールと [GT](/docs/platform/core/reference/gt-class/constructor) クラスの初期化を済ませておいてください。

## ファイル翻訳の仕組み [#file-translation-works]

ファイルはジョブとして翻訳されます。

1. ソースファイルをアップロードします。
2. ファイルを翻訳用にエンキューします。
3. 翻訳のステータスを確認します。
4. 翻訳済みファイルをダウンロードします。

ファイル翻訳で複数回の呼び出しを使うのは、Project では多くの場合、多数のファイルを翻訳するためです。手順を分けることで、API をより柔軟に利用できます。たとえば、ファイルのバッチ処理、失敗した処理の再試行、ジョブのポーリング、準備ができた時点での出力のダウンロードがしやすくなります。

ファイルをアップロードするとジョブが開始されます。複数のファイルをアップロードすると、複数のジョブが開始されます。詳しくは、[uploadSourceFiles](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) メソッドと [queryFileData](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) メソッドを参照してください。

## 1. ソースファイルをアップロードする [#upload]

このガイドでは、例として次の英語のJSONファイルを翻訳します：

```json
{
  "hello": "Hello",
  "world": "World"
}
```

ファイルを読み込み、内容を整形したうえで、[uploadSourceFiles](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) を呼び出してアップロードします。

```typescript title="src/index.ts"
import fs from 'fs';
import path from 'path';
import { FileUpload } from 'generaltranslation/types';

// (i) ファイルの内容を読み込む
const filePath = path.join(process.cwd(), 'en.json');
const fileContents = fs.readFileSync(filePath, 'utf8');

// (ii) ファイルの内容をフォーマットする
const fileUpload: FileUpload = {
  content: fileContents,
  fileName: filePath,
  fileFormat: 'JSON',
  locale: 'en',
};
const files = [ { source: fileUpload } ];

// (iii) ファイルをアップロードする
const { uploadedFiles } = await gt.uploadSourceFiles(
  files,
  {
    sourceLocale: 'en'
  }
);
```

レスポンスとして、ファイル参照の一覧が返されます。これにより、後でファイルを翻訳用にエンキューしたり、ファイルのステータスを確認したり、翻訳済みファイルをダウンロードしたりできます。

```ts title="Output"
[
  {
    fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
    versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
    branchId: '123456789',
    fileName: '/Users/demo/en.json',
    fileFormat: 'JSON'
  }
]
```

## 2. 翻訳のためにファイルをエンキューする [#enqueue]

アップロードしたファイル参照と対象ロケールを指定して、[enqueueFiles](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) を使用します。この例では、スペイン語 (`es`) に翻訳します。

```typescript title="src/index.ts"
const fileUploadRef = {
  fileId: uploadedFiles[0].fileId,
  versionId: uploadedFiles[0].versionId,
  branchId: uploadedFiles[0].branchId,
  fileName: uploadedFiles[0].fileName,
  fileFormat: uploadedFiles[0].fileFormat,
};

const enqueueResult = await gt.enqueueFiles(
  [fileUploadRef],
  {
    sourceLocale: 'en',
    targetLocales: ['es'],
  }
);
```

レスポンスは、ジョブ情報を含む結果を返します。

```ts title="Output"
{
  jobData: {
    'job-123456': {
      sourceFileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      targetLocale: 'es',
      projectId: 'your-project-id',
      force: false
    }
  },
  locales: ['es'],
  message: 'Successfully enqueued 1 file translation jobs in 1 batch(es)'
}
```

## 3. ファイルのステータスを確認する [#status]

翻訳済みファイルがダウンロード可能な状態まで完了しているかどうかは、[queryFileData](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) を使用して確認できます。

```typescript title="src/index.ts"
const { fileId, versionId, branchId } = uploadedFiles[0];

const status = await gt.queryFileData({
  translatedFiles: [
    {
      fileId,
      versionId,
      branchId,
      locale: 'es',
    },
  ],
});
```

ファイルがまだ翻訳中の場合、`completedAt` は `null` です。完了すると、タイムスタンプが入ります:

```ts title="Output"
{
  translatedFiles: [
    {
      fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
      versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
      branchId: '123456789',
      locale: 'es',
      completedAt: '2024-01-15T12:00:00Z'
    }
  ]
}
```

## 4. 翻訳済みファイルをダウンロードする [#download]

最後に、[downloadFile](/docs/platform/core/reference/gt-class-methods/translation/download-file) メソッドで翻訳済みファイルをダウンロードします。

```typescript title="src/index.ts"
const { fileId, branchId } = uploadedFiles[0];

const content = await gt.downloadFile({
  fileId,
  branchId,
  locale: 'es',
});
```

レスポンスとして、翻訳済みファイルの内容が返されます。この例では、次の内容が返されます。

```json title="Output"
{
  "hello": "Hola",
  "world": "Mundo"
}
```
## Next steps

- /docs/platform/core/guides/translating-strings
- /docs/platform/core/guides/locale-codes