# General Translation Integrations: プログラマティック API URL: https://generaltranslation.com/ja/docs/integrations/payload/reference/api.mdx Docs index: https://generaltranslation.com/llms.txt Description: サーバーコードから gt-payload を呼び出し、エクスポートされている結果の型と管理画面用コンポーネントを確認します。gt-payload のエクスポートに関する API リファレンスです。 ルートパッケージは、サーバーサイドでの翻訳を行う関数とその型をエクスポートします。`gt-payload/client` と `gt-payload/rsc` の各サブパスは、[`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) が Payload の管理パネルに登録するコンポーネントを公開しています。 ## Exports [#exports] | エクスポート | エントリーポイント | 説明 | | -------------------------------------------------------------------------- | ------------------- | -------------------------------------- | | [`translateDocument`](#translate-document) | `gt-payload` | 1つのコレクションドキュメントまたはグローバルを翻訳します。 | | [`translateSite`](#translate-site) | `gt-payload` | サポートされているすべてのドキュメントとグローバルを翻訳します。 | | [`saveTranslations`](#save-translations) | `gt-payload` | 1つのターゲットについて、現在のロケールの値を保存します。 | | [`saveSiteTranslations`](#save-site-translations) | `gt-payload` | サイト全体について、現在のロケールの値を保存します。 | | [`gtPlugin`](#plugin) | `gt-payload` | Payload の設定に管理画面のワークフローを追加します。 | | [`GtDocumentControls`](#admin-components) | `gt-payload/client` | ドキュメント単位の翻訳コントロール。 | | [`GtNavLink`](#admin-components) | `gt-payload/client` | サイト全体の翻訳ビューへのリンク。 | | [`GtRunsProvider`](#admin-components) | `gt-payload/client` | 未完了の翻訳実行を再開します。 | | [`GtTranslationsClient`](#admin-components) | `gt-payload/client` | 翻訳ビューのクライアント側コンテンツ。 | | [`GtTranslationsView`](#admin-components) | `gt-payload/rsc` | `/translations` に登録されるサーバービュー。 | | [`GtPluginOptions`](#gtpluginoptions) | `gt-payload` | `gtPlugin` が受け付けるオプション。 | | [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) | `gt-payload` | 単一ドキュメントを対象とする操作の入力。 | | [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) | `gt-payload` | サイト全体を対象とする操作の入力。 | | [`TranslateTarget`](#translatetarget) | `gt-payload` | コレクションドキュメントまたはグローバルの識別情報。 | | [`TranslateResult`](#translateresult-and-localeresult) | `gt-payload` | 1つのターゲットの翻訳結果。 | | [`LocaleResult`](#translateresult-and-localeresult) | `gt-payload` | 1つの対象ロケールの結果。 | | [`SkippedReason`](#skippedstring-and-skippedreason) | `gt-payload` | 文字列が書き込まれなかった理由。 | | [`SkippedString`](#skippedstring-and-skippedreason) | `gt-payload` | スキップ済みのキーとその理由。 | | [`SiteResult`](#siteresult-and-documentresult) | `gt-payload` | サイト全体の翻訳結果。 | | [`DocumentResult`](#siteresult-and-documentresult) | `gt-payload` | ターゲットとその結果のペア。 | | [`SaveTranslationsResult`](#savetranslationsresult) | `gt-payload` | ローカルでの編集内容の保存結果。 | | [`GtClient`](#gtclient) | `gt-payload` | プラグインが必要とする General Translation のメソッド。 | ## `translateDocument` [#translate-document] **input** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **戻り値** `Promise` コレクションドキュメントまたはグローバルを 1 件アップロードし、そのジョブの完了を最大 1 時間待機したうえで、完了した翻訳を Payload に書き込みます。 ```ts import { GT } from 'generaltranslation'; import { translateDocument } from 'gt-payload'; const result = await translateDocument({ payload, gt: new GT({ projectId: process.env.GT_PROJECT_ID, apiKey: process.env.GT_API_KEY, sourceLocale: payload.config.localization ? payload.config.localization.defaultLocale : undefined, }), target: { collection: 'pages', id: pageId }, locales: ['es', 'fr'], }); ``` 想定内のドキュメント、権限、ジョブ、翻訳のエラーについては、例外を投げずに結果の中で失敗として報告されます。ただし、予期しない操作が失敗した場合は、Payload やクライアントの呼び出しが reject されることがあります。 ## `translateSite` [#translate-site] **input** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **戻り値** `Promise` 翻訳可能なローカライズ対象のフィールドを持つすべてのコレクションドキュメントとグローバルを列挙し、1 つのバッチでまとめて翻訳します。翻訳されたロケールがなく、エラーも発生していないドキュメントは `documents` に含まれません。 ```ts import { translateSite } from 'gt-payload'; const result = await translateSite({ payload, gt, locales: ['es', 'fr'], user, }); ``` ## `saveTranslations` [#save-translations] **input** [`TranslateDocumentInput`](#translatedocumentinput-and-translatesiteinput) · **戻り値** `Promise` 1つのターゲットについて、Payload の現在のロケール値を General Translation に送信します。新しい翻訳ジョブはキューに追加しません。翻訳元ドキュメントが General Translation にまだ登録されていない場合は、この関数が先にそのドキュメントをアップロードします。 ```ts import { saveTranslations } from 'gt-payload'; const result = await saveTranslations({ payload, gt, target: { global: 'site-settings' }, locales: ['es', 'fr'], user, }); ``` ## `saveSiteTranslations` [#save-site-translations] **input** [`TranslateSiteInput`](#translatedocumentinput-and-translatesiteinput) · **戻り値** `Promise<{ documents: DocumentResult[] }>` [`translateSite`](#translate-site) が対象とするすべてのターゲットに対して、ローカルでの編集内容の保存 ワークフローを呼び出します。 ```ts import { saveSiteTranslations } from 'gt-payload'; const result = await saveSiteTranslations({ payload, gt, locales: ['es', 'fr'], user, }); ``` ## `gtPlugin` [#plugin] **型** `(options?: GtPluginOptions) => Plugin` Payload プラグインを返します。各オプションと副作用の詳細については、[Payload プラグインの設定](/docs/integrations/payload/reference/plugin-configuration)を参照してください。 ## 入力の型 [#input-types] ### `GtPluginOptions` ```ts type GtPluginOptions = { projectId?: string; apiKey?: string; customMapping?: CustomMapping; client?: GtClient; }; ``` ### `TranslateDocumentInput` と `TranslateSiteInput` ```ts type TranslateDocumentInput = { payload: Payload; gt: GtClient; target: TranslateTarget; locales: string[]; saveLocalEdits?: boolean; user?: TypedUser | null; }; type TranslateSiteInput = Omit; ``` | プロパティ | 説明 | 型 | 任意 | デフォルト | | ---------------- | ---------------------------------------------- | ------------------------------------- | --- | --------------------------- | | `payload` | 初期化済みの Payload インスタンス。 | `Payload` | いいえ | — | | `gt` | アップロード、ジョブ、ダウンロード、および短いリトライに使用するクライアント。 | [`GtClient`](#gtclient) | いいえ | — | | `target` | コレクションのドキュメントまたはグローバル。ドキュメント操作でのみ使用します。 | [`TranslateTarget`](#translatetarget) | いいえ | — | | `locales` | 処理対象の Payload ロケールコード。ソースロケールと重複したロケールは除外されます。 | `string[]` | いいえ | — | | `saveLocalEdits` | 翻訳前に既知のロケールの編集内容を保存し、送信できない編集内容を保持します。 | `boolean` | はい | `false` | | `user` | 読み取りと書き込みにアクセスルールが適用される Payload ユーザー。 | `TypedUser \| null` | はい | Payload Local API のサーバー側の動作 | ### `TranslateTarget` ```ts type TranslateTarget = | { collection: string; id: string | number } | { global: string }; ``` コレクションの ID はそのコレクション内でのみ一意であるため、コレクションと ID の両方の値を組み合わせて General Translation のファイル識別子とします。グローバルの場合はスラッグを使用します。 ## 結果の型 [#result-types] ### `TranslateResult` と `LocaleResult` ```ts type TranslateResult = { error?: string; usageLimitReached?: true; locales: Record; }; type LocaleResult = | { status: 'applied'; applied: string[]; skipped: SkippedString[]; } | { status: 'failed'; error: string; }; ``` `error` はターゲット単位の失敗を表します。`usageLimitReached` は、General Translation がステータス `402` で処理を拒否した場合にのみ含まれます。 `applied` には、Payload に書き込まれた安定したフィールドキーが格納されます。`skipped` には、書き込まれなかった翻訳対象の文字列とその理由が示されます。 ### `SkippedString` と `SkippedReason` ```ts type SkippedString = { key: string; reason: SkippedReason; }; type SkippedReason = | 'removed' | 'broken_markup' | 'missing' | 'unsaved_edit'; ``` | 理由 | 意味 | | --------------- | ---------------------------------------------------- | | `removed` | ソースの行、ブロック、またはフィールドが存在しません。 | | `broken_markup` | 返されたリッチテキストまたはリンクを安全に再構築できませんでした。 | | `missing` | ソースキーに対応する翻訳済みの値が返されませんでした。 | | `unsaved_edit` | Payload の編集を送信できなかったため、`saveLocalEdits` によって保持されました。 | ### `SiteResult` と `DocumentResult` ```ts type DocumentResult = { target: TranslateTarget; result: T; }; type SiteResult = { error?: string; documents: DocumentResult[]; }; ``` `DocumentResult` は、部分的な成功と失敗を、それぞれの対象となるコレクションドキュメントまたはグローバルに紐づけて保持します。 ### `SaveTranslationsResult` ```ts type SaveTranslationsResult = { error?: string; locales: Record< string, | { status: 'saved'; unsaved?: number } | { status: 'no_translations'; unsaved?: number } | { status: 'failed'; error: string } >; }; ``` `unsaved` は、リンクがソースと異なるためにプラグインが送信できなかった文字列の数です。 ### `GtClient` `GtClient` は、`generaltranslation` の `GT` クラスのうち、プラグインが使用する部分を抜き出したものです。 ```ts type GtClient = Pick< GT, | 'uploadSourceFiles' | 'enqueueFiles' | 'awaitJobs' | 'downloadFileBatch' | 'uploadTranslations' | 'checkJobStatus' | 'translateMany' | 'customMapping' >; ``` 本番環境では `GT` インスタンスを使用してください。この型はより限定的なため、テストダブルも使用できます。 ## 管理画面コンポーネント [#admin-components] このプラグインは、以下のエクスポートを import map のパスで登録します。 | コンポーネント | エントリーポイント | 役割 | | ---------------------- | ------------------- | --------------------------------------------- | | `GtDocumentControls` | `gt-payload/client` | ドキュメントまたはグローバルに **Translate** ボタンとドロワーを追加します。 | | `GtNavLink` | `gt-payload/client` | **翻訳** ナビゲーションリンクを追加します。 | | `GtRunsProvider` | `gt-payload/client` | 管理パネルを開いている間、未完了の実行を検出して処理を進めます。 | | `GtTranslationsClient` | `gt-payload/client` | サイト全体のコントロールとカバレッジテーブルを描画します。 | | `GtTranslationsView` | `gt-payload/rsc` | クライアントビューを Payload の管理画面テンプレートでラップします。 | これらのコンポーネントは個別に登録せず、[`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) を追加してください。これらがエクスポートされているのは、Payload が生成する import map でプラグイン設定を解決できるようにするためです。 ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.