# generaltranslation: General Translation Core SDK: クイックスタート
URL: https://generaltranslation.com/ja/docs/core/quickstart.mdx
---
title: クイックスタート
description: generaltranslation ライブラリのクイックスタート
---
## 概要
このガイドでは、generaltranslation ライブラリの基本的な使い方を解説します。
文字列の翻訳とファイルの翻訳について扱います。
***
## 最初の文字列を翻訳する
### 1. 環境変数を用意する
最初のステップでは、`GT_PROJECT_ID` と `GT_API_KEY` を作成します。
どちらも完全無料で作成でき、翻訳サービスを利用できるようになります。
[`API Keys` ページ](https://dash.generaltranslation.com/api-keys)に移動し、`Create API Key` をクリックします。
API キーの名前を入力して、`Create` をクリックします。
General Translation は、個人プロジェクトや個人開発者、コミュニティを支援するため、無料枠でも非常に高いレート制限を提供しています。
### 2. GT クラスを初期化する
[`GT`](/docs/core/class/constructor) クラスを初期化し、`GT_PROJECT_ID` と `GT_API_KEY` を安全に渡します。
```typescript title="src/index.ts"
import { GT } from 'generaltranslation';
const gt = new GT({
projectId: 'your-project-id',
apiKey: 'your-api-key',
});
```
### 3. 最初の文字列を翻訳する
[`translate`](/docs/core/class/methods/translation/translate) メソッドを呼び出して、文字列を翻訳します。
翻訳したい文字列と、対象のロケールを渡します。
```typescript title="src/index.ts"
const result = await gt.translate('Hello, world!', 'es'); // Spanish
if (result.success) {
console.log(result.translation); // "¡Hola, mundo!"
} else {
console.error(`Translation failed: ${result.error}`);
}
```
ロケールコードを確認したい場合は、[サポートされているロケール](/docs/platform/supported-locales) ページを参照してください。
***
## 最初のファイルを翻訳する
このガイドは、[最初の文字列を翻訳する](/docs/core/quickstart#translate-your-first-string)ガイドの手順 1 と 2 をすでに完了しており、
`GT_PROJECT_ID`、`GT_API_KEY`、および `GT` クラスのインスタンスがあることを前提としています。
たとえば、`en.json` というファイルをスペイン語に翻訳するとします。
```json title="en.json"
{
"hello": "Hello",
"world": "World"
}
```
ファイルを翻訳するには、次の4つの手順を実行します。
1. ファイルをアップロードする
2. ファイルを翻訳キューに追加する
3. ファイルのステータスを確認する (任意)
4. 翻訳済みファイルをダウンロードする
#### なぜ1回の呼び出しではないのでしょうか？ 通常は、一度に多数のファイルを翻訳したい場合があります
この処理を4つの明確な手順に分けることで、API をより柔軟に利用できるようになります。
### 1. ファイルをアップロードする
ファイルをアップロードすると、[`uploadSourceFiles`](/docs/core/class/methods/translation/upload-source-files) メソッドからファイル参照の一覧が返されます。
これにより、あとでそのファイルを翻訳キューに追加したり、ファイルのステータスを確認したり、翻訳済みファイルをダウンロードしたりできます。
```typescript title="src/index.ts"
import fs from 'fs';
import path from 'path';
import { FileUpload } from 'generaltranslation';
// (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. 翻訳対象としてファイルをキューに追加する
次の手順では、[`enqueueFiles`](/docs/core/class/methods/translation/enqueue-files) メソッドを使って、翻訳先のロケールを選択します。
ここでは、スペイン語に翻訳します。
```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"
{
jobId: 'job-123456',
locales: [ 'es' ],
message: 'Creating 1 translation(s).'
}
```
### 3. ファイルのステータスを確認する
では、ファイルはアップロードされましたが、ダウンロードできる状態になったことはどうやって確認すればよいのでしょうか？
ファイルのステータスは、[`queryFileData`](/docs/core/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. 翻訳済みファイルをダウンロードする
最後に、[`downloadFile`](/docs/core/class/methods/translation/download-file) メソッドを使って、翻訳済みファイルをダウンロードできます。
```typescript title="src/index.ts"
const { fileId, branchId } = uploadedFiles[0];
const content = await gt.downloadFile({
fileId,
branchId,
locale: 'es',
});
```
翻訳済みのファイル内容が返されます。
```ts title="Output"
{
"hello": "Hola",
"world": "Mundo"
}
```