DEVDOCS-6385 - Multi-lang text search

docs/storefront/headless/products/multi-language-search.mdx

@@ -0,0 +1,108 @@
+---
+title: Multi-language Product Search with GraphQL
+description: Learn how to perform product searches in multiple languages using the Storefront GraphQL API.
+keywords: multi language, graphql, product search, translations
+---
+
+# Multi-language Product Search with GraphQL
+
+BigCommerce's Storefront GraphQL API enables merchants to deliver localized shopping experiences by supporting multi-language product search. This guide explains how to use the API to search for products in a shopper's preferred language.
+
+## Overview
+
+To enable multi-language product search, ensure your store has both:
+- Translated product names and descriptions
+- Multi-language settings enabled in the BigCommerce admin
+
+When these are set, the Storefront GraphQL API automatically returns product search results in the shopper's preferred language, determined by the `Accept-Language` HTTP header or customer settings. If no preference is provided, the store's default language is used. The API uses the request's locale to select the correct translations for product fields, so no special query arguments are needed.
+
+## Searchable Fields
+
+The following fields are included in the multi-language search index:
+- Product name
+- Product description
+- Variant option names and values (when present)
+- Custom field names and values (when present)
+
+Search terms match these fields in the selected language.
+
+## Example Query
+
+<Tabs items={['Request', 'Response']}>
+<Tab>
+
+```graphql filename="Example query: Search for Products" showLineNumbers copy
+query SearchProductsInLanguage {
+  search {
+    searchProducts(filters: { searchTerm: "shirt" }) {
+      products(first: 10) {
+        edges {
+          node {
+            entityId
+            name
+            description
+            customFields {
+              name
+              value
+            }
+            options {
+              displayName
+              values {
+                label
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+</Tab>
+<Tab>
+
+```json filename="Example response: Search for Products" showLineNumbers copy
+{
+  "data": {
+    "search": {
+      "searchProducts": {
+        "products": {
+          "edges": [
+            {
+              "node": {
+                "entityId": 123,
+                "name": "Chemise",
+                "description": "Chemise en coton pour homme.",
+                "customFields": [
+                  { "name": "Matière", "value": "Coton" }
+                ],
+                "options": [
+                  {
+                    "displayName": "Taille",
+                    "values": [{ "label": "M" }, { "label": "L" }]
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+</Tab>
+</Tabs>
+
+## Best Practices
+
+- Set the shopper's language in your client (e.g., using the `Accept-Language` HTTP header).
+- Translate all product content in the BigCommerce admin for complete localization.
+- Test search results in each supported language to verify accuracy.
+
+## Learn More
+
+- [Faceted Textual Search](./faceted-textual-search)
+- [Storefront GraphQL API Reference](https://developer.bigcommerce.com/docs/storefront/graphql)