Payload CMSプラグイン
エディターの保存動作を変えずに、Payloadのローカライゼーションスキーマを公開し、ソースコンテンツの変更をLingo.devに通知します。
Lingo.devでは、Payloadのどのフィールドにローカライズ可能なテキストが含まれ、そのソースコンテンツがいつ変更されたかを把握する必要があります。@lingo.dev/payloadcmsは、このための2つの接続手段として、認証が必要なスキーマエンドポイントと、任意で有効にできるソース変更通知を提供します。翻訳対象の選択と書き戻しは、Payload連携で設定します。
プラグインを登録する #
既存のPayload 3アプリケーションに、次をインストールします。
npm install @lingo.dev/payloadcms@0.1.5アプリケーションの既存のプラグインリストにlingoを追加します。ローカライゼーション設定はそのまま残してください。
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
localization: {
locales: ["en", "fr"],
defaultLocale: "en",
},
plugins: [lingo()],
});ここでは関連するフィールドのみを示しており、これだけで動作する完全なCMS設定ではありません。既存のコレクション、グローバル、データベースアダプター、エディター、その他の必須設定は残してください。
このパッケージはlingoとLingoPluginOptionsをエクスポートします。lingo()はPayloadプラグインを返し、指定できるオプションはwebhookUrl?: stringのみです。このURLを指定せずに登録してもスキーマエンドポイントは公開されるため、自動通知を設定する前にスキーマ検出を設定できます。
Payload認証でスキーマを確認する #
プラグインは既存のエンドポイントを残したまま、PayloadのAPIベースパス(通常は/api/lingo/schema)からの相対パスとしてGET /lingo/schemaを追加します。既知のコレクションまたはグローバルを指定してリクエストします。
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepageアプリケーションで使用しているスラッグを指定してください。このハンドラーを利用するには、認証済みのPayloadユーザーである必要があります。未認証のリクエストには401、エンティティが未指定または不明な場合は404が返されます。連携は、設定済みのPayload認証情報を使ってこのエンドポイントを読み取ります。
レスポンスには、フィールド名、型、ローカライゼーションフラグ、入れ子構造、関連する解決済みの既定値が含まれます。また、テキストの特定に必要な、サポート対象の入れ子のグループ、配列、ブロック、タブ、Lexicalのブロックスキーマも含まれます。Payloadの設定全体をシリアライズするのではなく、関係のない管理画面やエディターの設定は省略します。
既定値の解決は、対象となるコンテンツ作成者向けのテキストフィールドに対して行われます。制限付きまたは非表示の既定値、構造用フィールド、解決またはシリアライズできない値は、既定値の出力から除外されます。スキーマは連携が確認できる内容を示すもので、取得しても翻訳はリクエストされません。
ソースの変更後に連携へ通知する #
Lingo.devでPayloadを接続したら、発行された権限付きURLをサーバー設定に保存し、プラグインに渡します。
const webhookUrl = process.env.LINGO_PAYLOAD_WEBHOOK_URL;
if (!webhookUrl) throw new Error("Set LINGO_PAYLOAD_WEBHOOK_URL for automatic notifications");
const plugin = lingo({ webhookUrl });既存のplugins配列で、lingo()の代わりにpluginを使用します。環境変数名はアプリケーション側で自由に決められます。このURL自体が通知を認可するため、ブラウザー向けのバンドル、コミットするソースコード、ログには含めないでください。
URLとlocalization.defaultLocaleの両方を設定すると、プラグインは既存のフックを残したまま、コレクションとグローバルにafterChangeフックを追加します。コレクションの通知では、スラッグ、ドキュメントID、任意項目のドキュメントステータスを送信します。グローバルの通知ではスラッグを送信します。送信データはドキュメント全体ではなく参照情報で、連携は設定済みの認証情報を使ってコンテンツを再取得します。
別のロケールを明示して行われた変更はスキップされます。これにより、翻訳先言語への書き戻しでソースの翻訳が繰り返し開始されるのを防ぎます。ロケールを明示しない変更では、通知が発生する場合があります。リクエストのタイムアウトは5秒です。通信エラーは無視されるため、エディターでの保存は完了できます。また、成功を示さないHTTPステータスが返されても、このフックが原因で保存が失敗することはありません。
接続結果を確認する #
まず、連携がPayloadの認証情報を使って目的のスキーマを読み取れることを確認します。次に、連携ワークフローを通じて、必要な権限のもとでソースを変更し、翻訳先ロケールの結果を確認します。ソースは保存されても翻訳先に届かない場合は、エディターでの保存成功だけで通知も届いたと判断せず、通知の受け付け状況と翻訳の実行状況を確認してください。
コレクション、翻訳先ロケール、ローカライゼーションエンジンは、Lingo.devの連携設定で選択します。これらはプラグインのオプションではないため、アプリケーション側のプラグイン登録を差し替えずに変更できます。