Resolving Multilingual Line Item Discrepancies in ESHOPMAN Draft Orders

For ESHOPMAN merchants leveraging the power of headless commerce and HubSpot CMS to manage international storefronts, accurate multilingual support is paramount. The ability to present product information in a customer's native language directly impacts user experience and conversion rates. Recently, a critical insight emerged from the ESHOPMAN community regarding a specific challenge with line item translations during draft order creation.

The Identified Challenge: Untranslated Line Items in ESHOPMAN Draft Orders

A user identified a bug where line items within draft orders were not being translated to the specified locale when the order was created in a single request via the ESHOPMAN Admin API. Specifically, when using the POST /admin/draft-orders endpoint with both a locale and items array in the same request, the product_title, product_description, and variant_title for those items would default to the primary language, ignoring the order's intended locale.

Key Observations and Reproduction Steps:

This issue is particularly notable because items added after the draft order's initial creation (e.g., via POST /admin/draft-orders/:id/edit/items) are translated correctly. This clearly indicates the problem is isolated to the order creation path. Here's a simplified way to reproduce the behavior within an ESHOPMAN environment:

1. Ensure the translation feature flag is enabled in your ESHOPMAN configuration and supported locales (e.g., en-US, fr-FR) are added.
2. Create a product with variants and add translations for its title, description, and variant titles for a secondary locale (e.g., fr-FR) using the Admin API (POST /admin/translations/batch).
3. Attempt to create a draft order in a single request using the ESHOPMAN Admin API:

   POST /admin/draft-orders
   {
     "region_id": "...",
     "locale": "fr-FR",
     "items": [{ "variant_id": "...", "quantity": 1 }]
   }

4. Retrieve the created draft order (GET /admin/draft-orders/:id) and inspect the first item. You will observe that product_title and variant_title are in the default language, not fr-FR.

For context, the user's ESHOPMAN backend setup involved:

{
    "name": "@dtc/backend",
    "version": "0.0.1",
    "dependencies": {
      "@eshopman/admin-sdk": "2.15.5",
      "@eshopman/cli": "2.15.5",
      "@eshopman/framework": "2.15.5",
      "@eshopman/eshopman": "2.15.5",
      "@eshopman/ui": "4.1.15"  
    },
    "devDependencies": {
      "@eshopman/test-utils": "2.15.5"
    }
  }

This issue was observed with Node.js v22.22.3 and PostgreSQL 16.14 on macOS 15.6.1.

Root Cause and Proposed Solution

The ESHOPMAN team confirmed the bug, noting that the underlying Node.js/TypeScript workflow responsible for creating orders, createOrderWorkflow, does not include a crucial step: getTranslatedLineItemsStep. This step is present in other sibling workflows that handle line item creation, such as addOrderLineItemsWorkflow, createCartWorkflow, and addToCartWorkflow, which explains why items added later are translated correctly.

A community member promptly proposed a straightforward fix:

• Add the getTranslatedLineItemsStep to the createOrderWorkflow.
• Ensure this translation step runs immediately after the line item creation step within the workflow.

Implementing this change would align the behavior of createOrderWorkflow with other ESHOPMAN workflows, ensuring consistent and accurate translation of line items regardless of whether they are added during initial order creation or subsequently. This is vital for maintaining data integrity and providing a seamless multilingual experience for merchants managing their storefronts through HubSpot CMS.

Impact for ESHOPMAN Users

This insight is highly valuable for ESHOPMAN developers and merchants. For developers building custom order flows or integrations with the Admin API, understanding this behavior is critical for ensuring correct data handling. For merchants, it highlights the importance of verifying translated content, especially when creating draft orders with pre-populated items for international customers. The proposed fix provides a clear path to resolving this discrepancy, reinforcing ESHOPMAN's commitment to robust and reliable headless commerce solutions integrated with HubSpot.