# General Translation Changelog: gt 2.23.0 / @generaltranslation/api 0.5.0: CLI からサインインしてプロジェクトをセットアップ
URL: https://generaltranslation.com/ja/blog/gt_v2_23_0_generaltranslation-api_v0_5_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: CLI からサインイン、プロジェクトのセットアップ、明示的な権限を指定したキーの作成が行えるようになりました。スクリプトやエージェントからヘッドレスでセットアップを実行することもできます。
Authors: Chenxin (Cyan) Yan
Published: 2026-09-29

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

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

[`gt init`](/docs/cli/reference/commands/init) を実行して、プロジェクトを設定します。サインインが必要になるのは、プロジェクトまたはキーを作成する場合のみです。

```bash
npx gt init
```

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

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

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

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

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

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

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

[`gt init`](/docs/cli/reference/commands/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 の認証情報](/docs/react/nextjs/config#credentials)を参照) 。

任意の権限を持つプロジェクトキーを追加で作成するには、[`gt api-key create`](/docs/cli/reference/commands/api-key-create) を使用します：

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

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

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

[`generaltranslation/api`](/docs/platform/core/reference/api-client) の [`paginate`](/docs/platform/core/reference/api-client#pagination) を使用すると、カーソルを自分で扱わずに、API キーでアクセスできるすべてのプロジェクトを順に処理できます：

```ts
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`](/docs/platform/core/reference/api-client#api-error) が throw されるようになりました。

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

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

## アップグレード

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

## Sitemap

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