Payload CMS
Payload 3のローカライズ対象フィールドを、リソース構造を保ったまま翻訳。ソースの変更をターゲットロケールに反映する方法も選べます。
Payloadには、ローカライズ対象の各フィールドに言語別の値を保存する仕組みが備わっています。Lingo.dev連携では、選択したソースフィールドを読み取り、ローカライゼーションエンジンで翻訳して、同じリソースのターゲットロケールに結果を書き戻します。コレクション、グローバル、公開の管理は、引き続きPayloadで行います。
Studio 2.5のナビゲーションでは、設定 → 連携ではなく、Studio 2.5 → 連携を開いてください。既存の接続用リンクやセットアップ用リンクは、引き続きご利用いただけます。
まずはリソースを一つ選び、手動で同期してみましょう。結果を確認し、編集に合わせて自動で翻訳したい場合は、ソース変更の通知を設定します。
Payload CMS連携の利用には、Enterpriseプランが必要です。現在の提供状況は料金をご覧ください。組織のプランで利用できない場合は、設定 → 連携でPayloadの横にご利用のプランでは利用できませんと表示されます。
Payloadとサービスユーザーを準備する #
ローカライゼーションを設定したPayload 3を使用してください。リッチテキストの翻訳はLexicalエディターに対応していますが、旧来のSlateエディターには対応していません。インスタンスには、Lingo.devからHTTPS経由でアクセスできる必要があります。
useAPIKey: trueを使用する認証コレクションに、サービスユーザーを作成します。通常はusersを使用します。翻訳対象のすべてのコレクションまたはグローバルに対して、このユーザーに読み取りと更新の権限を付与してください。書き込みは、このユーザーによる操作として記録されます。ゲートウェイで追加のヘッダーが必要な場合は、接続時に指定し、その値を秘密情報として管理してください。
接続のソースロケールは、プラグインが変更を監視するPayloadのlocalization.defaultLocaleに合わせてください。ソースとターゲットのコードは、Payloadに設定したコードと完全に一致する必要があります。enとen-USは異なるロケールを表します。接続先のLingo.dev組織で利用できるローカライゼーションエンジンを選択してください。接続を追加できない場合は、組織内の権限と、接続機能を利用できる契約になっているかを確認してください。
インスタンスを接続してスキーマを公開する #
設定 → 連携を開き、Payload CMSの接続を選択します。接続名、インスタンスのルートアドレス、認証コレクション、サービス用のAPIキー、必要なゲートウェイヘッダーを入力します。接続を選択すると、アクセスが検証され、接続が保存されます。その後に表示されるウェブフックURLは、自動通知用に控えておいてください。
Payloadプロジェクトにプラグインをインストールします。
pnpm add @lingo.dev/payloadcms既存のplugins配列にlingoを追加します。以下の抜粋はプラグインの設定部分です。プロジェクトのコレクション、グローバル、ローカライゼーション、その他のプラグインの設定は、そのまま残してください。
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
plugins: [
lingo({ webhookUrl: process.env.LINGO_WEBHOOK_URL }),
],
});プラグインは常にGET /api/lingo/schemaを登録します。Lingo.devは、このエンドポイントを使ってローカライズ対象のフィールドを特定します。プラグインのインストール前でも接続は作成できますが、翻訳にはスキーマのエンドポイントが必要です。
自動通知を有効にするには、接続のウェブフックURLをPayloadの環境変数LINGO_WEBHOOK_URLにコピーします。このURLを持っているだけで通知リクエストを送信できるため、秘密の認証情報と同様に扱ってください。プラグインや環境設定を変更した後は、Payloadを再デプロイしてください。手動翻訳のみを行う場合は、webhookUrlを省略します。その場合も、プラグインによってスキーマは公開されます。
Studioの接続済みからインスタンスを選び、セットアップを選択します。使用するローカライゼーションエンジン、ソースロケールとターゲットロケール、書き戻しモードを指定します。続行を選択し、翻訳するコレクションとグローバルを選びます。公開モードについては、以下で説明します。
一つのリソースを翻訳する #
ローカライズ対象の短いテキストフィールドを含むコレクションまたはグローバルを一つと、ターゲットロケールを一つ選びます。同期する前に、Payloadで現在のソースとターゲットの値を控えておいてください。
どのように公開したいかに合わせて、モードを選択します。
| モード | ソースと書き戻し |
|---|---|
| 下書き | 下書きのソースコンテンツを読み取り、翻訳したフィールドを下書きとして書き込みます。Payloadでレビューできます。 |
| 公開 | 公開済みの変更を処理し、翻訳を公開済みの状態で書き込みます。 |
Payloadでは、ドキュメントごとに共有の下書きを1つ保持し、全体をまとめて公開します。そのため、未公開の編集内容が残っている公開済みドキュメントに翻訳を書き込むと、その編集内容も公開されてしまいます。これを防ぐため、公開モードでは該当するドキュメントを変更せず、翻訳の失敗を報告します。Payloadで編集内容を公開するか、公開済みのバージョンに戻してから、もう一度同期を実行してください。これらの編集内容を確認するには、APIキーのユーザーに、選択したコレクションとグローバルのすべてのバージョンに対するreadVersionsアクセス権が必要です。このアクセス権がフィルターで制限されている場合、公開モードでは該当する公開済みドキュメントを変更しません。一度も公開されていないドキュメントは、このチェックの対象外です。公開モードで翻訳が書き込まれても、下書きのまま維持されます。チェックは書き込みの直前に毎回行われるため、チェック後から書き込みまでの間に保存された下書きは、翻訳とともに公開される可能性があります。同期による書き込み中は、対象ドキュメントの下書きを保存せず、同期後に公開状態を確認してください。下書きの動作はPayloadの設定によっても異なります。更新をテストする際は、現在公開中のバージョンを確認してください。
同期を実行し、そのワークフロー実行を開いて、Payloadの実際のターゲットフィールドを確認します。表現、リンク、リッチテキストの構造、ロケール、公開状態を確認してください。続いて、そのコンテンツを利用するサイトでも表示を確認します。接続しただけでは、カタログは翻訳されません。
初回の同期では、既存の完成済みの翻訳を置き換えずに保持します。不足しているフィールドを補完し、現在の値がPayloadの既定値をそのまま繰り返しているだけのフィールドも補完します。フィールドが保持された場合は、置き換えを依頼する前に、その値がこの状態に当てはまるかを確認してください。
リソースとフィールドを選択する #
コレクションとグローバルのテーブルには、設定が保存される同期スイッチがあります。コレクションを選択すると、その中のドキュメントが対象になり、グローバルを選択すると、そのリソースが対象になります。ヘッダーのアクションでは、有効になっているリソースを処理します。行を選択して実行するアクションがある場合は、接続に保存されている対象範囲の設定を変更せず、選択した範囲をキューに追加します。
これらのリソース内では、スキーマに基づいて、ローカライズ対象のtext、textarea、LexicalのrichTextフィールドが選択されます。ローカライズ対象のグループ、配列、ブロック、タブ内にあるテキストもたどり、入れ子やインラインのリッチテキストブロックも対象にします。
ローカライズ対象ではないフィールドや、id、blockType、blockNameなどの構造に関わる値は、翻訳対象のテキストに含まれません。選択肢、数値、リレーション、アップロード、コード、任意のJSONは、コレクションを選択しただけでは翻訳対象になりません。別のテキストフィールドを対象に加えるには、Payloadでそのフィールドのローカライゼーションを設定し、再デプロイしてください。
Lexicalの処理では、インライン書式やリンクをまたいで文の文脈を保ち、リンク、メディア、ブロックを含むツリーを再構築します。対象範囲を広げる前に、代表的なドキュメントでテストしてください。特に、独自のフィールドやエディター拡張機能を使用している場合は、事前の確認が重要です。
ソースの変更に翻訳を追従させる #
ウェブフックURLと既定のロケールを設定すると、ソースロケールの変更後にプラグインが通知を送信します。通知に含まれるのはリソースへの参照であり、ドキュメント本文ではありません。Lingo.devは、保存済みのサービス認証情報でコンテンツを再取得し、接続の対象範囲とモードを適用したうえで、近いタイミングで届いた通知をまとめて処理します。
ターゲットロケールへの書き込みで、翻訳が再実行されることはありません。また、通知に失敗しても編集者の保存処理は失敗しないため、保存できたことだけでは通知が届いたかどうかは確認できません。変更が反映されていない場合は、実行履歴を確認し、手動同期でコンテンツの整合性を取ってください。下書きモードでは、下書きの保存も対象になります。ターゲットロケールの保存や対象範囲外のリソースは、この接続ではソースの変更と見なされません。
ソースの変更やターゲットコンテンツの不足には、同期を使用します。同期では、コンテンツを利用可能な基準データと比較します。以前のソースの保存データを利用できない場合は、復旧処理によって該当するコンテンツが再生成されることがあります。手動編集がすべて保持されるとは限らないため、差分を確認してください。ターゲットロケールを追加した後は、同期を実行して内容を補完します。
手動編集したフィールドも含め、選択した翻訳を置き換えたい場合は、再翻訳を使用します。たとえば、ローカライゼーションエンジンへの指示を大きく変更した場合は、ソースが変わっていなくても、新たな翻訳が必要になることがあります。リクエストは、その接続で進行中の実行に続く形でキューに追加されます。同じアクションを繰り返し送信しても、完了は早まりません。
変更されたドキュメントや一部のみ書き込まれたドキュメントを復旧する #
書き戻しの段階で、ソースコンテンツを再取得します。処理計画の作成後に編集者が内容を変更していた場合は、異なるリビジョンや配列順序に翻訳値を適用せず、そのドキュメントをスキップします。その後の同期で、新しいソースとの整合性を取ります。
実行が失敗またはキャンセルされても、成功した書き込みは保持されます。ワークフロー実行で、完了、最新、スキップ、失敗、キャンセルの状態を見分け、再試行する前に該当するリソースを確認してください。停止が利用できる場合は、進行中の処理をキャンセルできます。ただし、書き込み済みのフィールドは元に戻りません。「最新」という結果は、選択した範囲に処理すべき変更がなかったことを意味します。
出力がまったく表示されない場合は、スキーマのエンドポイント、フィールドのローカライゼーション設定と型、サービスユーザーの読み取り・更新権限、ロケールコードの完全一致、リソースの同期対象設定、モード、ウェブフックの環境設定を確認してください。インスタンスにアクセスできない場合やキーが拒否される場合は、問題を解消してから再翻訳を依頼してください。
設定を変更する、または接続を解除する #
リソースの選択、ロケール、ローカライゼーションエンジン、モードはStudioで変更します。接続名の変更や認証情報の管理は、設定 → 連携で行います。これらの設定を変更しても、ウェブフックURLは変わりません。
APIキーを更新するには、設定 → 連携で接続を開き、キーを置き換えるを選択します。同じ認証コレクションのキーを入力し、インスタンスで引き続き必要なカスタムヘッダーをすべて再入力してください。保存済みのヘッダーは、今回指定したヘッダーで置き換えられます。
インスタンスのアドレスを変更するには、新しい接続が必要です。自動通知の利用を再開する前に、新しい接続の翻訳対象範囲を設定し、Payloadの環境設定を新しいウェブフックURLに更新してください。
接続を解除すると、その接続のローカル履歴と同期状態が削除され、以後の読み取りと書き込みが停止します。既存の翻訳済みコンテンツはPayloadに残ります。古いウェブフックの環境変数の値またはフックを削除し、サービスキーが不要になった場合は、別途そのキーを失効させてください。
新しい接続では、新たな基準データが作成されます。初回の同期では、保持条件を満たす既存の翻訳を残し、不足分を補完します。以前の接続のローカル実行履歴は復元されません。ほかの新規接続と同じように、初回の実行結果を確認してください。