クイックスタート
generaltranslation ライブラリのクイックスタートガイド
概要
このガイドでは、generaltranslation ライブラリの基本的な使い方を順を追って説明します。 文字列翻訳とファイル翻訳を取り上げます。
最初の文字列を翻訳する
1. 環境変数を取得する
最初の手順は、GT_PROJECT_ID と GT_API_KEY を作成することです。
これは完全に無料で、翻訳サービスにアクセスできるようになります。
API Keys ページに移動し、Create API Key をクリックします。
APIキーの名称を入力し、Create をクリックします。
General Translation は、個人プロジェクト、ソロ開発者、コミュニティを支援するために、非常に寛大な無料のレート制限を提供しています。
2. GT クラスを初期化する
GT クラスを初期化し、GT_PROJECT_ID と GT_API_KEY を安全に渡します。
import { GT } from 'generaltranslation';
const gt = new GT({
projectId: 'your-project-id',
apiKey: 'your-api-key',
});3. 最初の文字列を翻訳する
文字列を翻訳するには、translate メソッドを呼び出します。
翻訳したい文字列と対象ロケールを渡します。
const { translation } = await gt.translate('Hello, world!', 'es'); // Spanish
console.log(translation); // "¡Hola, mundo!"ロケールコードを確認したい場合は、対応ロケール ページを参照してください。
はじめてのファイルを翻訳する
このガイドは、はじめての文字列を翻訳する のステップ1と2を完了し、
GT_PROJECT_ID、GT_API_KEY、および GT クラスのインスタンスを用意していることを前提としています。
en.json というファイルをスペイン語に翻訳したいとします。
{
"hello": "こんにちは",
"world": "世界"
}ファイルを翻訳するには、次の4つの手順に従います。
- ファイルをアップロードする
- ファイルを翻訳キューに登録する
- ファイルのステータスを確認する（任意）
- 翻訳済みファイルをダウンロードする
なぜ1回の呼び出しにしないのですか？
多くの場合、複数のファイルをまとめて翻訳したいニーズがあります。 手順を4つに分けることで、APIの使い方における柔軟性が大きく向上します。
1. ファイルをアップロードする
ファイルをアップロードすると、uploadSourceFiles メソッドによってファイル参照のリストが返されます。
これにより、後でファイルを翻訳キューに投入し、ステータスを確認し、翻訳済みファイルをダウンロードできます。
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'
}
);ファイル参照のリストを返します：
[
{
fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
fileName: '/Users/demo/en.json',
fileFormat: 'JSON'
}
]2. ファイルを翻訳キューに追加する
次のステップは、enqueueFiles メソッドで翻訳対象の対応ロケールを選択します。
この例では、スペイン語に翻訳します。
const fileUploadRef = {
fileId: uploadedFiles[0].fileId,
versionId: uploadedFiles[0].versionId,
fileName: uploadedFiles[0].fileName,
fileFormat: uploadedFiles[0].fileFormat,
};
const enqueueResult = await gt.enqueueFiles(
[fileUploadRef],
{
sourceLocale: 'en',
targetLocales: ['es'],
});これにより、ファイル参照のリストが返されます:
{
translations: [],
data: {
'41726368696562616c64204d6342616c64792074686973206973206a6f6b652e': {
fileName: '/Users/demo/en.json',
versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121'
}
},
locales: [ 'es' ],
message: '1件の翻訳を作成しています。'
}3. ファイルのステータスを確認する
さて、ファイルをアップロードしました。では、いつダウンロード可能になったと分かるのでしょうか？
checkFileTranslations メソッドを使って、ファイルのステータスを確認できます。
const status = await gt.checkFileTranslations([{
versionId: uploadedFiles[0].versionId,
fileName: uploadedFiles[0].fileName,
locale: 'es'
}]);ファイルの翻訳が進行中の場合、出力には対応する翻訳は含まれません。
{
translations: [
{
locale: 'es',
metadata: {},
fileId: '41726368696562616c64204d6342616c64792074686973206973206a6f6b652e',
fileName: '/Users/demo/en.json',
versionId: '427269616e204c6f75206d6f7265206c696b65204c696f6e2042726f20686121',
id: 'skl44z0ieuvdcomw38zb5chv',
isReady: true,
downloadUrl: '/v2/project/translations/files/skl44z0ieuvdcomw38zb5chv/download'
}
]
}4. 翻訳済みファイルをダウンロードする
最後に、downloadTranslatedFile メソッドで翻訳済みファイルをダウンロードします。
const { translation } = await gt.downloadTranslatedFile({
fileId: uploadedFiles[0].fileId,
locale: 'es',
versionId: uploadedFiles[0].versionId,
});これにより、翻訳済みのファイル内容が返されます。
{
"hello": "こんにちは",
"world": "世界"
}このガイドはどうでしたか？