Payload CMS

Payload CMS をローカライゼーションエンジンに接続し、対象のコレクションとグローバルを選択すると、Lingo.dev がローカライズ対象のフィールドを指定したロケールに翻訳し、各ロケールに対応する Payload へ書き戻します。

ローカライゼーションが有効で、Lexical リッチテキストエディタを使用している Payload 3 プロジェクトに対応しています。旧式の Slate エディタには対応していません。翻訳対象は、ローカライズされた text、textarea、richText フィールドです。ドキュメント内のそれ以外の内容はそのまま維持されます。

Payload 連携は組織単位で有効になります。Settings -> Integrations に表示されない場合は、ご連絡ください。こちらで有効化します。

始める前に#

必要なものは 3 つです。

• ローカライゼーション設定済みのPayload 3。 ソースロケールとターゲットロケールが、Payload の設定内のロケールと一致していることを確認してください。
• API キーを持つサービスユーザー。 認証コレクション（通常は useAPIKey: true）で users を設定し、Lingo.dev 用のユーザーを作成したうえで、Payload の管理画面からそのユーザーの API キーを生成します。このユーザーには、翻訳対象にしたいすべてのコレクションとグローバルに対する read と update 権限が必要です。
• ローカライゼーションエンジン。 その glossary、ブランドボイス、ルールが翻訳内容を左右します。

Payload インスタンスを接続する#

pnpm add @lingo.dev/payloadcms

import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";

export default buildConfig({
  // ...your collections, globals, and localization config
  plugins: [
    lingo({
      webhookUrl: process.env.LINGO_WEBHOOK_URL,
    }),
  ],
});

翻訳対象を選ぶ#

接続ページには Collections、Globals、Runs の 3 つのタブがあります。

スコープはコレクション単位・グローバル単位で設定します。選択したコレクション内のすべてのドキュメントが対象になります。スコープ、ロケール、エンジン、下書き設定を変更するには、ページヘッダーの Edit configuration をクリックしてください。変更は再デプロイ不要で次回実行から反映されます。

各ドキュメント内で何が翻訳されるかは、Payload のフィールド設定で決まります。

リッチテキストは Lexical ツリーとして翻訳されます。書式、リンク、アップロード、ブロック構造はそのまま保持され、置き換わるのは中のテキストだけです。太字やリンクで途中が分かれている文でも、1 つの文としてまとめて翻訳されます。

フィールドを対象に含めるには、Payload でそのフィールドを localized: true としてマークして再デプロイしてください。次回の実行で反映されます。

同期と再翻訳#

自動実行。 プラグインで webhookUrl を設定すると、ソースロケールのドキュメントまたはグローバルを保存するたびに、Lingo.dev に通知されます。短時間に行われた複数の保存はデバウンスされ、1回の実行にまとめられます。他のロケールでの保存、下書きの保存（Translate draft saves がオンの場合を除く）、およびスコープ外のコンテンツは無視されます。

手動実行。 各コレクション、グローバル、ドキュメント行には 2 つのボタンがあります。

コレクションを開くと、その中のドキュメントへ移動して 1 件ずつ同期できます。どちらのタブでも、各項目の最終同期日時が表示されます。

接続しただけでは翻訳は始まりません。すでにあるコンテンツを翻訳するには、各コレクションとグローバルで Sync をクリックしてください。後からターゲットロケールを追加する場合も同じで、次回の Sync で埋められます。

1 つの接続で同時に進行する実行は 1 件だけです。追加のリクエストはキューに入り、順番に開始されます。キュー待ちまたは実行中の行では、ボタン表示が Syncing... になります。

実行を確認する#

Runs タブには、すべての実行についてステータス、トリガー（Webhook または Manual、sync または retranslate）、開始時刻、所要時間が表示されます。キュー待ちまたは実行中の実行は、この一覧からキャンセルできます。

実行を開くと、現在のステージ（Payload からの読み取り、翻訳、書き戻し）、全体の進捗、ターゲットロケールごとの進捗、対象のドキュメント・コレクション・グローバルを確認できます。各項目には Payload 管理画面へのリンクがあります。

実行が失敗しても、すでに書き込まれた内容はそのまま保持されます。エラーメッセージには書き込まれなかったドキュメントが表示され、次回のSyncで再試行されます。実行中にエディターが保存したドキュメントはスキップされ、次の実行で処理されます。

翻訳の保存先#

各翻訳は、Payload 独自のローカライゼーションモデルに従い、対応するターゲットロケールの同じドキュメントまたはグローバルに書き込まれます。書き込まれるのは翻訳対象のフィールドのみで、それ以外のフィールドは変更されません。書き戻しはサービスユーザーとして実行され、新しい実行はトリガーされません。

既存の翻訳は保持されます。ドキュメントの初回 Sync では、ターゲットロケールにすでに入っている内容はそのまま残り、不足しているフィールドだけが翻訳されます。Payload のデフォルト値のままのフィールドは未入力として扱われます。既存の翻訳を置き換えたい場合は Retranslate を使ってください。

下書きと公開#

Translate draft saves がオフ（デフォルト）の場合、実行が開始されるのは公開済みの変更のみで、翻訳は書き込まれ次第すぐに公開されます。Payload はドキュメント全体を公開するため、そのドキュメント上の未公開の下書き編集も翻訳と一緒に公開されます。

これをオンにすると、下書き保存でも実行が開始されます。Lingo.dev はソースの最新の下書きを読み取り、各翻訳を下書きとして書き込みます。Payload で誰かがその翻訳を公開するまでは、読者に見える内容は変わりません。翻訳品質を確認している間や、翻訳がレビューを通る運用に向いています。

接続を管理する#

webhook URL を更新する#

接続ページのヘッダーメニューを開き、Regenerate webhook URL を選択します。古いURLはその時点ですぐに無効になります。LINGO_WEBHOOK_URL を更新して、再デプロイしてください。接続を編集しても、URLは変わりません。

接続を解除する#

Settings -> Integrations -> Payload CMS から接続を解除できます。これにより、接続情報、実行履歴、何が翻訳済みかの記録が削除されます。すでに書き込まれた翻訳は Payload に残ります。その後、設定から LINGO_WEBHOOK_URL またはプラグインを削除してください。

制限#

トラブルシューティング#

接続時に "Payload rejected the API key" と表示される場合。 キー、認証コレクションの slug、そのコレクションで useAPIKey が有効になっているかを確認してください。

コレクションまたはグローバルに "No read + update" と表示される場合。 そのコレクションのアクセス設定で、サービスユーザーに read と update 権限を付与し、設定画面を開き直してください。

最初の実行で "The Lingo plugin isn't installed" と表示される場合。 Payload 設定の @lingo.dev/payloadcms に plugins を追加して再デプロイしてください。プラグインがなくても接続はできますが、Sync はできません。

Payload で公開しても実行が始まらない場合。 LINGO_WEBHOOK_URL が設定されていること、localization が設定済みであること、そのコレクションまたはグローバルがスコープに含まれていること、保存がソースロケールで行われたこと、そして下書き保存ではなく公開であることを確認してください。

フィールドが翻訳されない。 そのフィールド自身または親に localized: true が設定されていないか、text、textarea、richText のいずれのフィールドでもありません。

接続に "Couldn't reach this Payload instance" と表示される場合。 インスタンスが稼働中か、キーがまだ有効か、ゲートウェイヘッダーが引き続き機能しているかを確認してください。Settings -> Integrations から接続を更新してください。

次のステップ#