貿易向けサイト構築における多言語フィールドマッピングのエラーを調査する方法

貿易サイトで多言語版を公開した後、技術評価担当者を最も悩ませるのは、翻訳品質ではなく、「管理画面にはコンテンツがあるのにフロント画面では空白になっている」「英語の商品ページに中国語のフィールドが表示される」「価格、単位、または画像が特定の言語でずれている」といった問題であることが少なくありません。このような現象の多くは単一障害ではなく、フィールド定義、言語識別子、データ構造、インターフェースのパラメータ間に不整合が生じていることに起因します。

チーム内で「貿易サイト構築における多言語フィールドマッピングで常にエラーが出る場合はどうすればよいか？」と繰り返し問われた際、直ちに言語パックを再構築したり、コンテンツを一括再送信したりすることは推奨されません。より確実な方法は、まずエラーが発生しているレイヤーを特定することです。ソースフィールドを取得できていないのか、マッピングルールの照合に失敗しているのか、それとも対象言語のデータが保存またはレンダリング時に上書きされているのかを確認します。以下の調査手順は、B2B貿易企業の公式サイト、越境ECモール、広告ランディングページ、およびERP、PIM、CMSから商品データを同期する多言語独立サイトに適用できます。

まず確認：エラーはどの処理経路で発生しているか

多言語フィールドマッピングは通常、単なる「翻訳」という作業ではなく、データ処理経路です。ソースシステムのフィールド → フィールドマッピングルール → 言語コンテンツオブジェクト → インターフェース転送 → ページテンプレートのレンダリング、という流れになります。ページ上で確認されるエラーが、必ずしもページレイヤーで発生しているとは限りません。

まず、代表的な商品またはページのレコードを1件選び、ソースデータ、インターフェースのリクエストボディ、インターフェースの戻り値、CMS管理画面での保存結果、およびフロント画面の最終出力をそれぞれ記録することを推奨します。データベース全体を使って調査せず、1件の「問題サンプル」を用いる方が差異を把握しやすくなります。たとえば、中国語名は正常でドイツ語名が空の場合、同一レコードのzh-CNとde-DEにおけるフィールドパス、フィールド値、公開状態を比較する必要があります。

インターフェースの戻り値に対象言語のフィールドが正しく存在するにもかかわらず、ページに表示されない場合は、テンプレート変数、キャッシュ、公開バージョンに注目します。一方、インターフェースリクエストの段階でフィールドが空、またはフィールド名が誤っている場合は、マッピング設定と上流データソースの処理に戻って確認する必要があります。

フィールド名が同じように見えても、実際には同一フィールドではない可能性がある

フィールド命名の不統一は、貿易サイト構築における多言語フィールドマッピングエラーの頻出原因です。特にERP、PIM、サイト構築システムをそれぞれ異なるチームが管理している場合、中国語名はproduct_name、英語インターフェースではname_en、ページコンポーネントではi18n.nameが使用されていることがあります。3者の意味が同じでも、システムが自動的に識別するとは限りません。

調査時は表示名だけでなく、フィールドの内部識別子、完全なパス、およびマッピング優先順位を確認する必要があります。よくある問題には次のものがあります。

• 大文字・小文字またはアンダースコアの違い：ProductName、product_name、productNameは、ほとんどのシステムでは同一フィールドとして扱われません。
• フィールドパスの階層エラー：対象フィールドがtranslations.en.titleであるべきところ、translation.en.titleと記述されている場合、保存時にエラーが出ないことがあっても、コンテンツは想定した位置に格納されません。
• 予約フィールドの競合：name、descriptionなどのフィールドは、プラットフォームで基本フィールドとして使用されている場合があり、拡張フィールドには明確な名前空間を採用する必要があります。
• マッピングの上書き：共通ルールが先にタイトルを書き込み、その後に言語専用ルールが空の値で上書きすると、最終的にフロント画面には空白のみが表示されます。

より信頼性の高い方法は、フィールド辞書を作成することです。業務名、ソースフィールド、対象フィールド、データ型、多言語対応の有無、デフォルト値、必須ルール、および管理システムを明記します。フィールド辞書は文書作成の負担ではなく、後から言語を追加する場合、テンプレートを調整する場合、インターフェース連携テストを行う場合の共通基準となります。

データ型を見落とさない：テキストが表示されても、構造が正しいとは限らない

多言語タイトルは通常文字列であり、問題は比較的分かりやすいものです。しかし、商品パラメータ、リッチテキストの詳細、仕様表、画像セット、SEOメタデータなどのフィールドには、配列やオブジェクトが含まれることが少なくありません。ソース側と対象側のデータ型が一致しないと、「値があるのに表示されない」「最初の項目しか表示されない」または「詳細ブロック全体が失われる」といった問題が発生しやすくなります。

特に数値フィールドには注意が必要です。価格、重量、寸法自体は必ずしも翻訳を必要としませんが、通貨記号、単位、3桁区切りの書式、税務に関する説明には通常、地域差があります。priceをそのまま翻訳可能なテキストとして処理すると、価格計算に使用できなくなる可能性があります。逆に、「USD 1,200 / set」を純粋な数値フィールドに格納すると、ECモールの決済または絞り込みロジックが破損する可能性があります。正しい方法は、数値、通貨、単位、表示文言を分けて管理することです。

言語コードの照合失敗は、「翻訳が反映されない」問題に見せかけられることが多い

言語パックまたは言語オブジェクトのキー値は、サイトルーティングおよびインターフェース仕様と一致していなければなりません。en、en-US、en-GBはいずれも英語を表しますが、システム上では3つの異なる言語識別子である場合があります。ポルトガル語、フランス語、スペイン語などの市場にも同様の問題があります。

技術評価の際には、「言語コードマッピング表」を公開前チェックに含めるべきです。フロント画面のURLではどのコードを使用するのか、管理画面の言語ではどのコードを使用するのか、インターフェースではどのコードを送信するのか、デフォルトのフォールバック言語は何かを確認します。サイトルートが/de/である一方、コンテンツサービスがde-DEしか返さない場合、ページには互換マッピングが存在するでしょうか。存在しなければ、システムが暗黙的に英語またはデフォルトの中国語へフォールバックし、コンテンツが混在する原因となる可能性があります。

言語パックの読み込みタイミングも確認する必要があります。一部のフロントエンドフレームワークでは、まずデフォルト言語でファーストビューをレンダリングし、その後非同期で対象言語に切り替えます。コンポーネントが言語状態の変化を監視していない場合、タイトルは英語に切り替わっていても、仕様パラメータはデフォルト言語のまま残ります。この場合、問題はコンテンツライブラリではなく、フロントエンドの状態管理とコンポーネント更新の仕組みにあります。

インターフェースのパラメータでは、「何を送信したか」と「システムがどう解釈するか」を同時に確認する

インターフェース連携テストでは、HTTP 200だけで成功と判断することはできません。多くのCMSやサイト構築プラットフォームは、未知のフィールドを受け入れ、不正なオブジェクトを無視し、デフォルト値で保存を完了することさえあります。その結果、インターフェースは成功していても、データは対象言語のレコードに格納されていません。

テスト環境ではリクエストとレスポンスのサンプルを保持し、次の内容を重点的に確認することを推奨します。リクエストヘッダーの文字セットはUTF-8か、言語パラメータはURL、Header、Bodyのどこに配置されているか、更新インターフェースは全量上書きか部分マージか、空文字列、null、フィールド欠落はそれぞれ「クリア」「更新しない」「デフォルト値を使用」のどれを意味するかです。一括同期時に呼び出し側がこの3つの状態を区別していなければ、翻訳済みコンテンツを誤って消去しやすくなります。

Webhook、定期同期、またはキュータスクをサポートするプラットフォームでは、タスクのべき等性も確認する必要があります。古いタスクが新しいタスクより後に実行されると、新しい翻訳が古いバージョンで上書きされる可能性があります。コンテンツのバージョン番号、更新タイムスタンプ、またはソースレコードのハッシュ値により書き込み順序を制御することで、このような再現しにくい「偶発的エラー」を防止できます。

実行可能な調査順序

1. 1件の問題データで再現し、本番環境で直接全件再実行しない。
2. ソースフィールドに値があることを確認し、ソースレコードの元の構造をエクスポートする。
3. フィールド辞書を照合する：内部フィールド名、オブジェクトパス、マッピング優先順位、データ型。
4. インターフェースのリクエストとレスポンスを取得し、対象言語コードと実際に書き込まれたフィールドを確認する。
5. CMS内の対象言語コンテンツ、公開状態、デフォルト言語のフォールバックルールを確認する。
6. キャッシュをクリアまたは回避し、テンプレート変数が正しい言語オブジェクトを読み取っているか検証する。
7. 修正後、少なくとも2言語、2種類のページテンプレート、リッチテキストを含む1件のデータで回帰テストを行う。

統合型のサイト構築・マーケティングシステムを採用している企業では、フィールドマッピングはSEOタイトル、Meta説明、商品構造化データ、広告ランディングページの文言、ソーシャルメディア共有情報にも影響します。そのため、修正時にはページ本文だけを検証してはいけません。易営宝のような海外独立サイト向けAIスマートサイト構築プラットフォームでは、多言語コンテンツ設定、ページ公開、海外プロモーションの連携において、フィールド仕様、言語ルール、テンプレート呼び出しをプロジェクト設定に統合することがより適しており、コンテンツチームと技術チームがそれぞれ別の命名体系を管理する状況を減らせます。

真に安定した多言語サイトは、単に「言語を切り替えられる」だけでは十分ではありません。すべての言語で、データソース、ページ表示、検索エンジンのクロールまで一貫性を保つ必要があります。一度のフィールドマッピング障害を、フィールド標準、インターフェース契約、回帰テスト体制の改善へと転換すれば、その後に小規模言語を追加したり、新しい製品ラインを接続したりする際、チームの負担は大幅に軽減されます。