Payload CMS

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

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

Payload CMS は Enterprise プランで利用できます。接続ページに Payload CMS はご利用中のプランに含まれていません と表示された場合は、ご連絡ください。こちらで対応します。

始める前に#

必要なものは 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、Workflow runs、Settings の四つのタブがあります。

スコープはコレクションごと、グローバルごとに設定します。Collections タブと Globals タブには、インスタンスで利用できるすべての項目が一行ずつ表示され、最後に同期した日時も確認できます。各行には Sync スイッチがあります。これをオンにすると、そのコレクション内のすべてのドキュメント、またはそのグローバルが、その時点以降対象になります。変更は切り替えた瞬間に保存され、再デプロイなしで次の実行に反映されます。表のヘッダーにあるスイッチを使うと、一覧内のすべてに対して Sync をオンまたはオフにできます。

no read + update と表示された行はロックされています。サービスユーザーがそれを読み取って更新できないため、翻訳できません。not localized yet と表示された行は、Sync がオフです。

ロケール、エンジン、モードは Settings タブで変更します。

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

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

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

同期と再翻訳#

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

手動実行。 二つのボタンがあり、それぞれ役割が異なります。

どちらもページヘッダーにあり、Sync がオンになっているすべての項目を対象にします。ヘッダーの Retranslate は、最初に確認を求めます。特定のコレクションまたはグローバルだけを実行するには、その行にチェックを入れてください。Queue sync (N) と Queue retranslation (N) が表示され、それらの行だけが対象になります。行にチェックを入れられるのは、その行の Sync スイッチがオンになってからです。

接続しただけでは何も翻訳されません。すでにある内容を翻訳するには、ページヘッダーの Sync をクリックしてください。あとからターゲットロケールを追加する場合も同じで、次の Sync で反映されます。

接続ごとに同時進行できる実行は一つだけです。追加のリクエストはキューに入り、順番に開始されます。

実行を確認する#

Workflow runs タブには、すべての実行が一覧表示されます。開始時刻、何がきっかけだったか（Webhook または Manual、続いて Sync または Retranslate）、対象ロケール、所要時間、ステータスを確認できます。キュー待ちまたは実行中の実行には Stop ボタンがあります。行を開くと、ロケールごとの結果を確認できます。

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

翻訳の保存先#

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

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

下書きと公開#

公開 モードでは、公開済みの変更だけが実行を開始し、翻訳は書き込まれるとすぐに公開されます。Payload はドキュメント全体を公開するため、そのドキュメントにある未公開の下書き編集も翻訳と一緒に公開されます。

下書き モードでは、下書き保存でも実行が開始されます。Lingo.dev はソースの最新の下書きを読み取り、各翻訳を下書きとして書き込みます。Payload で誰かが翻訳を公開するまで、読者に見える内容は変わりません。翻訳品質を評価しているときや、翻訳がレビューを経る場合に使ってください。

モードはあとから Settings タブで変更できます。

接続を管理する#

設定#

Settings タブには、その接続が読み取るインスタンス、Sync がオンになっているコレクションとグローバル、そして接続が Working か Cannot be reached かが表示されます。ここでは名前、ソースロケール、ターゲットロケール、エンジン、モードを変更できます。どの変更でも webhook URL はそのまま維持されるため、再デプロイは不要です。

アドレスとエーピーアイキーは接続作成時に設定され、その後は変更できません。Lingo.dev の接続先を別のアドレスまたはキーに変更するには、いったん切断してから再度接続してください。

接続を解除する#

Settings タブの下部にある Disconnect を使うと、Lingo.dev はそのインスタンスへの読み取りと書き込みを停止します。これにより、接続、実行履歴、何が翻訳済みかの記録が削除されます。すでに書き込まれた翻訳は Payload に残ります。その後、設定から LINGO_WEBHOOK_URL またはプラグインを削除してください。

制限#

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

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

コレクションまたはグローバルに「no read + update」と表示される。 そのコレクションのアクセス設定で、サービスユーザーに読み取り権限と更新権限を付与してから、接続ページを再読み込みしてください。行の Sync スイッチのロックが解除されます。

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

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

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

Settings タブで接続が Cannot be reached と表示される。 インスタンスが稼働中であること、キーが引き続き有効であること、そしてゲートウェイヘッダーが引き続き機能していることを確認してください。既存の接続ではアドレスとキーを編集できないため、どちらかが変更された場合は、切断して再接続し、新しい webhook URL で LINGO_WEBHOOK_URL を更新してください。

次のステップ#