# General Translation Platform: ファイルの翻訳
URL: https://generaltranslation.com/ja/docs/platform/core/guides/translating-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: generaltranslation ライブラリでファイルをアップロード、翻訳、ダウンロードする方法。

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

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

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

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

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

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

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

アップロードするとソースファイルのレコードが作成されます。続いて [`enqueueFiles`](/docs/platform/core/reference/gt-class-methods/translation/enqueue-files) を呼び出すと、処理がまだ必要なソースファイルとターゲットロケールの組み合わせごとに 1 つのジョブが開始されます。 (詳しくは、[`uploadSourceFiles`](/docs/platform/core/reference/gt-class-methods/translation/upload-source-files) メソッドと [`queryFileData`](/docs/platform/core/reference/gt-class-methods/translation/query-file-data) メソッドを参照してください) 。

SVG ファイルの場合は、UTF-8 の XML ソースを `fileFormat: 'SVG'` とともに渡してください。翻訳では、シェイプとスタイルを保持したままテキストノードが更新されます。非同期のレイアウト処理により、指定されたフォントサイズを保持しつつ、テキストの再センタリングやはみ出した翻訳の短縮が行われる場合があるため、ファイルが完了するまで待ってからダウンロードしてください。不正な形式の XML は拒否されます。

## 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 type { 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 content = await gt.downloadFile({
  fileId,
  versionId,
  branchId,
  locale: 'es',
});
```

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

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

## Next steps

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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.