gt@2.23.0 / @generaltranslation/api@0.5.0

gt@2.23.0 では、アカウントへのサインイン、プロジェクトの選択、スコープを限定したキーの作成、スクリプトによるセットアップをターミナルから行えるようになりました。あわせてリリースされた @generaltranslation/api@0.5.0 と generaltranslation@9.5.2 では、ページネーションを自動で処理するプロジェクト検出機能が追加されています。

ガイド付きセットアップから始める

gt init を実行して、プロジェクトを設定します。サインインが必要になるのは、プロジェクトまたはキーを作成する場合のみです。

npx gt init

セットアップを実行せずにサインインするには gt login を、別のデバイスで承認するには npx gt login --no-browser を使用します。どちらの場合も、人による承認が必要です。

gt whoami はサインイン中の識別情報を確認し、gt logout は保存されたログイン情報を削除します。無人で実行するワークフローでは、CI プロバイダーのシークレットストアに保存した、スコープを限定した API キーを使用してください。

スクリプトやエージェントからセットアップを実行する

セットアップ時の質問にはすべて、対応するフラグが用意されています。ターミナルがない環境や --no-interactive を指定した場合、gt init はファイルを変更する前に、不足しているオプションを一覧表示します。また、--json を指定すると、サインイン、ハンドオフ、結果の各イベントが出力されます:

npx gt init --no-interactive --json --defaults --locales fr es --no-dev-credentials

--defaults はローカル設定の推奨値をそのまま採用しますが、プロジェクトやキーを作成することはありません。

プロジェクトとキーの権限を選択する

gt init では、アクセス可能なプロジェクトを選択するか、権限を持つ Organization 内にプロジェクトを新規作成し、そのプロジェクトの ID と開発用のRuntimeキーを .env.local に保存できます。

このキーに付与されるのは project:translations:generate のみです。ローカルでのRuntime翻訳専用であり、CLI によるアップロードや CI には使用できません。既存の GT_API_KEY の値は変更されません。Next.js App Router プロジェクトでは NEXT_PUBLIC_GT_PROJECT_ID と NEXT_PUBLIC_GT_DEV_API_KEY が設定されるため、開発環境ではクライアントコンポーネントも翻訳されます。どちらも本番環境のビルドには含めないでください (Next.js の認証情報を参照) 。

任意の権限を持つプロジェクトキーを追加で作成するには、gt api-key create を使用します：

npx gt api-key create --project-id your-project-id \
  --name "Runtime translations" \
  --permission project:translations:generate

キーを作成し、選択した各権限を付与できる権限が必要です。このコマンドはシークレットを一度だけ表示するため、安全な場所に保管してください。CI では、この生成専用の例をそのまま使い回すのではなく、ワークフロー全体に必要な権限を選択してください。デプロイするブラウザ向けやモバイル向けのバンドルには、API キーを絶対に含めないでください。

型付き API 呼び出しを使用してジョブの結果を確認する

generaltranslation/api の paginate を使用すると、カーソルを自分で扱わずに、API キーでアクセスできるすべてのプロジェクトを順に処理できます：

import { listProjects, paginate } from 'generaltranslation/api';

for await (const project of paginate(listProjects, { client })) {
  console.log(project.id, project.name);
}

createApiClient クライアントでは、throwOnError を指定した呼び出しで HTTP エラーが発生すると、HTTP ステータスを code に格納した ApiError が throw されるようになりました。

API クライアントのポーリングヘルパーを使うと、翻訳ジョブの完了を待機できます。timeout した場合は complete: false が返されます。なお、完了したからといって、すべてのジョブが成功したとは限りません。翻訳をダウンロードする前に、ジョブの結果を確認してください。

診断メッセージのフォーマット機能を、公開エントリポイント generaltranslation/diagnostics から利用できるようになりました。ツールは Core のエントリポイント全体をインポートしなくても、対処方法を示すメッセージをフォーマットできます。

アップグレード

プロジェクトと Organization の一覧取得に関する変更に対応してください。 API はこれらを projects や orgs ではなく items で返すようになり、この変更以前に発行されたカーソルは受け付けられなくなりました。以前のバージョンの CLI では、gt init でこれらを一覧表示できません。HTTP や SDK を直接呼び出している場合は、items を読み取るようにし、ページネーションを最初からやり直してください。
throw する呼び出しでは ApiError をキャッチしてください。 throwOnError を指定した呼び出しおよび awaitJobs で HTTP エラーが発生した場合、デコードされたレスポンスボディではなく ApiError が throw されるようになりました。throwOnError を指定しない呼び出しでは、引き続き error にボディが返されます。
src/gt.config.json を移動してください。 CLI はこのファイルを読み込まなくなりました。プロジェクトのルートに移動するか、--config src/gt.config.json を指定してください。
gt auth と --key-type を置き換えてください。 アカウント認証には login を、対話形式のプロジェクトセットアップには init を使用し、追加の認証情報はキーを明示的に作成してください。gt configure は副作用のない代替手段ではありません。セットアップによっては、依存関係のインストールや認証情報のプロビジョニングが行われる場合があります。
Runtime 用とツール用の認証情報は分けて管理してください。 GT_DEV_API_KEY は引き続きフレームワークの Runtime 設定です。サインインしただけでは Runtime SDK の認証情報は構成されません。明示的に指定した API キーは、引き続き CLI に保存された login より優先されます。詳しくは認証情報の選択を参照してください。
リトライの前提を確認してください。 管理用の POST リクエストは、ネットワークエラーやサーバーエラーを自動でリトライしません。ただし、リトライが有効な場合、429 レスポンスは引き続きリトライされることがあります。Core のランタイム翻訳では、これらのエラーも 429 レスポンスも自動ではリトライされません。プロジェクトやキーの作成を安易に繰り返さないでください。リクエストが成功するたびに、新しいリソースが作成されます。
サポート対象の互換 API は引き続き利用できます。 Core の devApiKey フォールバックと getProjectData は引き続き利用できますが、非推奨です。apiKey を使用し、新たにプロジェクト情報を取得する場合は getProjectInfo の使用を推奨します。
検証と結果の変更に対応してください。 サポートされていないモデルプロバイダーの値は、リクエストの送信前にエラーになります。フォントのアップロード結果には deduped フィールドが含まれなくなりました。