gtx-cli@2.3.0

2025年9月12日

Fernando Aviles

gtx-cli2.3.0translateuploadsetup

概要

gtx-cli 2.3.0 では、translate コマンドと upload コマンドの動作を変更し、翻訳パイプラインの可視性を向上させました。

Translate

これまで translate は、翻訳の実行をトリガーすると同時に、バックグラウンドで一度きりのプロジェクトセットアップ（dashboard に表示される context や glossary の生成）も行っていました。

小規模なプロジェクトでは処理は高速でしたが、大規模なコードベースではセットアップに時間がかかりすぎてタイムアウトが発生し、翻訳が失敗したように見えることがありました。

ユーザーには translate が失敗したように見える一方で、実際にはセットアップは非同期で完了し、翻訳も生成されているもののダウンロードされないため、結果として不完全で分かりにくい UX につながっていました。

セットアップ

セットアップは現在、別のステップになっています。タイムアウトがほとんど発生しないよう最適化しました。

とはいえ、セットアップが失敗する可能性があることも踏まえ、翻訳処理はセットアップの完了に「依存」しないようになりました。現在のパイプラインはおおよそ次のような流れです。

Upload: ファイルをアップロードし、成功を確認します。
Setup (only if needed): セットアップジョブを開始して完了を待ちます。失敗またはタイムアウトした場合は、そのまま次に進みます。
Translate: すでにアップロード済みのファイルに基づいて翻訳ジョブを作成します。

セットアップが時間内に完了すればそれで問題ありませんし、失敗またはタイムアウトしても処理は続行され、その結果をお知らせします。翻訳は引き続き取得できます。

npx gtx-cli translate を実行したときに表示される内容:

翻訳を開始しています...

翻訳対象ファイル:
  - your/file/path.mdx
  - ...

General Translation APIへファイルをアップロード中...
✔ ファイルのアップロードが完了しました

プロジェクトをセットアップ中...

# セットアップが成功した場合
セットアップが完了しました。

# セットアップがタイムアウトした場合
⚠ セットアップがタイムアウトしました — セットアップをスキップして続行します: セットアップ生成の待機中にタイムアウトしました

# セットアップが失敗した場合
⚠ セットアップに失敗しました — セットアップをスキップして続行します: <error message>

# いずれの場合も翻訳処理を続行します
12件の翻訳を作成中
[0/12] 翻訳完了
your/file/path.mdx [es]

この変更により、たとえセットアップが万が一失敗した場合でも、翻訳が必ず生成されることを保証できるようになりました。

また、この変更によって、翻訳に影響を与えるコンテンツをどのように・どこで生成しているかを、より明確に把握できるようになった点も気に入っています。さらに、新しいセットアップ手順を追加しても翻訳処理が止まることは決してないため、安心して手順を追加できます。

アップロード

upload もさらに柔軟になりました。以前のバージョンでは、常にソースファイルとその翻訳ファイルをセットで送信することを前提としていましたが、これはすべてのワークフローに当てはまりません。現在は次のことができます:

ソースファイルのみ をアップロードする（まだ翻訳はない状態）。
ソース + 翻訳をまとめて アップロードする。

リポジトリの構造と設定から、翻訳ファイルはこれまでどおり自動検出されます。アップロードすると、すぐにダッシュボードにファイルが表示されます。

gt.config.json が次のような内容だとします:

{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

npx gtx-cli upload を実行する:

# ソースのみ（ローカル翻訳が見つかりません）：
アップロードを開始しています...

アップロード対象のファイル：
  - src/i18n/en/common.json -> es, fr
  ...

General Translationに1ファイルをアップロード中...
✔ ファイルのアップロードが完了しました

完了！

# ダッシュボードには次のように表示されます：
#   src/i18n/en/common.json
# 対応する翻訳はまだありません。

ローカル翻訳が存在し、自動検出された場合：

アップロードを開始しています...

アップロード対象ファイル:
  - src/i18n/en/common.json -> es, fr

General Translationに3個のファイルをアップロード中...
✔ ファイルのアップロードが完了しました

完了!

# ダッシュボードには以下が表示されます:
#   src/i18n/en/common.json
# ロケールドロップダウンにスペイン語版とフランス語版の翻訳も表示されます。

あるロケールの翻訳ファイルが存在しない場合、そのロケールについてはソースのみをアップロードし、不足している翻訳はスキップします。

ローカルに翻訳があってもソースだけをアップロードしたい場合は、upload を実行する前に gt.config.json からそのロケールを削除してください。

{
  "defaultLocale": "en",
  "locales": [],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

アップロードは既存の翻訳を上書きします

注意: upload を実行すると、特定の file/locale に対して検出・アップロードされた翻訳ファイルは、その file/locale に現在保存されている内容を置き換えます。

ソースのみをアップロードしたい場合は、upload の前に gt.config.json から target locales を削除してください。

変更内容を事前に確認する必要がある場合は、別プロジェクトを使用するか、アップロード前に現在の翻訳をエクスポートしてください。

存在しない翻訳はスキップされ、存在する翻訳は上書きされます。

戻る

gtx-cli@2.3.0

2025年9月12日

Fernando Aviles

gtx-cli2.3.0translateuploadsetup

Upload: ファイルをアップロードし、成功を確認します。
Setup (only if needed): セットアップジョブを開始して完了を待ちます。失敗またはタイムアウトした場合は、そのまま次に進みます。
Translate: すでにアップロード済みのファイルに基づいて翻訳ジョブを作成します。

npx gtx-cli translate を実行したときに表示される内容:

翻訳を開始しています...

翻訳対象ファイル:
  - your/file/path.mdx
  - ...

General Translation APIへファイルをアップロード中...
✔ ファイルのアップロードが完了しました

プロジェクトをセットアップ中...

# セットアップが成功した場合
セットアップが完了しました。

# セットアップがタイムアウトした場合
⚠ セットアップがタイムアウトしました — セットアップをスキップして続行します: セットアップ生成の待機中にタイムアウトしました

# セットアップが失敗した場合
⚠ セットアップに失敗しました — セットアップをスキップして続行します: <error message>

# いずれの場合も翻訳処理を続行します
12件の翻訳を作成中
[0/12] 翻訳完了
your/file/path.mdx [es]

この変更により、たとえセットアップが万が一失敗した場合でも、翻訳が必ず生成されることを保証できるようになりました。

アップロード

ソースファイルのみ をアップロードする（まだ翻訳はない状態）。
ソース + 翻訳をまとめて アップロードする。

gt.config.json が次のような内容だとします:

{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

npx gtx-cli upload を実行する:

# ソースのみ（ローカル翻訳が見つかりません）：
アップロードを開始しています...

アップロード対象のファイル：
  - src/i18n/en/common.json -> es, fr
  ...

General Translationに1ファイルをアップロード中...
✔ ファイルのアップロードが完了しました

完了！

# ダッシュボードには次のように表示されます：
#   src/i18n/en/common.json
# 対応する翻訳はまだありません。

ローカル翻訳が存在し、自動検出された場合：

アップロードを開始しています...

アップロード対象ファイル:
  - src/i18n/en/common.json -> es, fr

General Translationに3個のファイルをアップロード中...
✔ ファイルのアップロードが完了しました

完了!

# ダッシュボードには以下が表示されます:
#   src/i18n/en/common.json
# ロケールドロップダウンにスペイン語版とフランス語版の翻訳も表示されます。

あるロケールの翻訳ファイルが存在しない場合、そのロケールについてはソースのみをアップロードし、不足している翻訳はスキップします。

ローカルに翻訳があってもソースだけをアップロードしたい場合は、upload を実行する前に gt.config.json からそのロケールを削除してください。

{
  "defaultLocale": "en",
  "locales": [],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

アップロードは既存の翻訳を上書きします

注意: upload を実行すると、特定の file/locale に対して検出・アップロードされた翻訳ファイルは、その file/locale に現在保存されている内容を置き換えます。

ソースのみをアップロードしたい場合は、upload の前に gt.config.json から target locales を削除してください。

変更内容を事前に確認する必要がある場合は、別プロジェクトを使用するか、アップロード前に現在の翻訳をエクスポートしてください。

存在しない翻訳はスキップされ、存在する翻訳は上書きされます。

戻る

gtx-cli@2.3.0

2025年9月12日

Fernando Aviles

gtx-cli2.3.0translateuploadsetup

Upload: ファイルをアップロードし、成功を確認します。
Setup (only if needed): セットアップジョブを開始して完了を待ちます。失敗またはタイムアウトした場合は、そのまま次に進みます。
Translate: すでにアップロード済みのファイルに基づいて翻訳ジョブを作成します。

npx gtx-cli translate を実行したときに表示される内容:

翻訳を開始しています...

翻訳対象ファイル:
  - your/file/path.mdx
  - ...

General Translation APIへファイルをアップロード中...
✔ ファイルのアップロードが完了しました

プロジェクトをセットアップ中...

# セットアップが成功した場合
セットアップが完了しました。

# セットアップがタイムアウトした場合
⚠ セットアップがタイムアウトしました — セットアップをスキップして続行します: セットアップ生成の待機中にタイムアウトしました

# セットアップが失敗した場合
⚠ セットアップに失敗しました — セットアップをスキップして続行します: <error message>

# いずれの場合も翻訳処理を続行します
12件の翻訳を作成中
[0/12] 翻訳完了
your/file/path.mdx [es]

この変更により、たとえセットアップが万が一失敗した場合でも、翻訳が必ず生成されることを保証できるようになりました。

アップロード

ソースファイルのみ をアップロードする（まだ翻訳はない状態）。
ソース + 翻訳をまとめて アップロードする。

gt.config.json が次のような内容だとします:

{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

npx gtx-cli upload を実行する:

# ソースのみ（ローカル翻訳が見つかりません）：
アップロードを開始しています...

アップロード対象のファイル：
  - src/i18n/en/common.json -> es, fr
  ...

General Translationに1ファイルをアップロード中...
✔ ファイルのアップロードが完了しました

完了！

# ダッシュボードには次のように表示されます：
#   src/i18n/en/common.json
# 対応する翻訳はまだありません。

ローカル翻訳が存在し、自動検出された場合：

アップロードを開始しています...

アップロード対象ファイル:
  - src/i18n/en/common.json -> es, fr

General Translationに3個のファイルをアップロード中...
✔ ファイルのアップロードが完了しました

完了!

# ダッシュボードには以下が表示されます:
#   src/i18n/en/common.json
# ロケールドロップダウンにスペイン語版とフランス語版の翻訳も表示されます。

あるロケールの翻訳ファイルが存在しない場合、そのロケールについてはソースのみをアップロードし、不足している翻訳はスキップします。

ローカルに翻訳があってもソースだけをアップロードしたい場合は、upload を実行する前に gt.config.json からそのロケールを削除してください。

{
  "defaultLocale": "en",
  "locales": [],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

アップロードは既存の翻訳を上書きします

注意: upload を実行すると、特定の file/locale に対して検出・アップロードされた翻訳ファイルは、その file/locale に現在保存されている内容を置き換えます。

ソースのみをアップロードしたい場合は、upload の前に gt.config.json から target locales を削除してください。

変更内容を事前に確認する必要がある場合は、別プロジェクトを使用するか、アップロード前に現在の翻訳をエクスポートしてください。

存在しない翻訳はスキップされ、存在する翻訳は上書きされます。

戻る

gtx-cli@2.3.0

2025年9月12日

Fernando Aviles

gtx-cli2.3.0translateuploadsetup

Upload: ファイルをアップロードし、成功を確認します。
Setup (only if needed): セットアップジョブを開始して完了を待ちます。失敗またはタイムアウトした場合は、そのまま次に進みます。
Translate: すでにアップロード済みのファイルに基づいて翻訳ジョブを作成します。

npx gtx-cli translate を実行したときに表示される内容:

翻訳を開始しています...

翻訳対象ファイル:
  - your/file/path.mdx
  - ...

General Translation APIへファイルをアップロード中...
✔ ファイルのアップロードが完了しました

プロジェクトをセットアップ中...

# セットアップが成功した場合
セットアップが完了しました。

# セットアップがタイムアウトした場合
⚠ セットアップがタイムアウトしました — セットアップをスキップして続行します: セットアップ生成の待機中にタイムアウトしました

# セットアップが失敗した場合
⚠ セットアップに失敗しました — セットアップをスキップして続行します: <error message>

# いずれの場合も翻訳処理を続行します
12件の翻訳を作成中
[0/12] 翻訳完了
your/file/path.mdx [es]

この変更により、たとえセットアップが万が一失敗した場合でも、翻訳が必ず生成されることを保証できるようになりました。

アップロード

ソースファイルのみ をアップロードする（まだ翻訳はない状態）。
ソース + 翻訳をまとめて アップロードする。

gt.config.json が次のような内容だとします:

{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

npx gtx-cli upload を実行する:

# ソースのみ（ローカル翻訳が見つかりません）：
アップロードを開始しています...

アップロード対象のファイル：
  - src/i18n/en/common.json -> es, fr
  ...

General Translationに1ファイルをアップロード中...
✔ ファイルのアップロードが完了しました

完了！

# ダッシュボードには次のように表示されます：
#   src/i18n/en/common.json
# 対応する翻訳はまだありません。

ローカル翻訳が存在し、自動検出された場合：

アップロードを開始しています...

アップロード対象ファイル:
  - src/i18n/en/common.json -> es, fr

General Translationに3個のファイルをアップロード中...
✔ ファイルのアップロードが完了しました

完了!

# ダッシュボードには以下が表示されます:
#   src/i18n/en/common.json
# ロケールドロップダウンにスペイン語版とフランス語版の翻訳も表示されます。

あるロケールの翻訳ファイルが存在しない場合、そのロケールについてはソースのみをアップロードし、不足している翻訳はスキップします。

ローカルに翻訳があってもソースだけをアップロードしたい場合は、upload を実行する前に gt.config.json からそのロケールを削除してください。

{
  "defaultLocale": "en",
  "locales": [],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

アップロードは既存の翻訳を上書きします

注意: upload を実行すると、特定の file/locale に対して検出・アップロードされた翻訳ファイルは、その file/locale に現在保存されている内容を置き換えます。

ソースのみをアップロードしたい場合は、upload の前に gt.config.json から target locales を削除してください。

変更内容を事前に確認する必要がある場合は、別プロジェクトを使用するか、アップロード前に現在の翻訳をエクスポートしてください。

存在しない翻訳はスキップされ、存在する翻訳は上書きされます。