Payload CMSプラグイン

エディターの保存動作を変えずに、Payloadのローカライゼーションスキーマを公開し、ソースコンテンツの変更をLingo.devに通知します。

Lingo.devでは、Payloadのどのフィールドにローカライズ可能なテキストが含まれ、そのソースコンテンツがいつ変更されたかを把握する必要があります。@lingo.dev/payloadcmsは、このための2つの接続手段として、認証が必要なスキーマエンドポイントと、任意で有効にできるソース変更通知を提供します。翻訳対象の選択と書き戻しは、Payload連携で設定します。

プラグインを登録する #

既存のPayload 3アプリケーションに、次をインストールします。

sh
npm install @lingo.dev/payloadcms@0.1.5

アプリケーションの既存のプラグインリストにlingoを追加します。ローカライゼーション設定はそのまま残してください。

ts
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を追加します。既知のコレクションまたはグローバルを指定してリクエストします。

text
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepage

アプリケーションで使用しているスラッグを指定してください。このハンドラーを利用するには、認証済みのPayloadユーザーである必要があります。未認証のリクエストには401、エンティティが未指定または不明な場合は404が返されます。連携は、設定済みのPayload認証情報を使ってこのエンドポイントを読み取ります。

レスポンスには、フィールド名、型、ローカライゼーションフラグ、入れ子構造、関連する解決済みの既定値が含まれます。また、テキストの特定に必要な、サポート対象の入れ子のグループ、配列、ブロック、タブ、Lexicalのブロックスキーマも含まれます。Payloadの設定全体をシリアライズするのではなく、関係のない管理画面やエディターの設定は省略します。

既定値の解決は、対象となるコンテンツ作成者向けのテキストフィールドに対して行われます。制限付きまたは非表示の既定値、構造用フィールド、解決またはシリアライズできない値は、既定値の出力から除外されます。スキーマは連携が確認できる内容を示すもので、取得しても翻訳はリクエストされません。

ソースの変更後に連携へ通知する #

Lingo.devでPayloadを接続したら、発行された権限付きURLをサーバー設定に保存し、プラグインに渡します。

ts
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の連携設定で選択します。これらはプラグインのオプションではないため、アプリケーション側のプラグイン登録を差し替えずに変更できます。