Implement multilingual site search with Cloudflare AI Search

We implemented it on our own company website, which uses Astro SSG + headless CMS.
The installation process itself was relatively straightforward, but since our site is multilingual, we encountered several pitfalls.

What is Cloudflare AI Search

Formerly called AutoRAG, it was renamed in September 2025. Note that most articles and old APIs you'll find in search results are under the previous name.

Here's the sequence of steps it performs.

Crawl → Markdown conversion → Chunk splitting → Embedding → Index construction for vectors + keywords

There are two API systems: search returns search results list, and chat/completions generates answers with RAG. We use only the former this time.

Configuration tips

Create an instance as follows.

• Select WebCrawl for the data source.
• Public URL as crawl target
• Set analysis type to sitemap
• Specify main element in content selector
• Analysis mode: static site
• Specify sitemap.xml for the particular sitemap
• Set embedding model to @cf/baai/bge-m3 (for Japanese sites)

The rest can remain at default settings.

Authentication and environment variables

Create an API token from your account.
Note: you need not only "AI Search: Read", but also "Edit" and "Execute" permissions.
Load the token via the environment variable AI_SEARCH_TOKEN.

Architecture: 1 API route + 1 component

Search calls the REST API from Astro's API route (which runs as a Pages Function). Since we can't expose the API token to the browser, proxying on the server side is essential. Pages Functions doesn't have an AI Search binding, so we're using raw fetch instead of the SDK.

// Astro の API ルート（Pages Functions として動く）
const res = await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${id}/ai-search/instances/${name}/search`,
  {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}` },
    body: JSON.stringify({
      query,
      ai_search_options: {
        retrieval: {
          retrieval_type: 'hybrid',
          max_num_results: 50
        },
      },
    }),
  }
);

We implemented just two files: an API route and a search UI component. As an addition to SSG, it's quite lightweight.

Narrowing search results to the displayed language on multilingual sites

For a typical site search, this would be fine, but in the multilingual case, because we're reading a sitemap.xml written in all languages, search results get mixed together.

The solution is to define a custom metadata locale and filter by filters during search. This ensures that only the language being viewed appears in search results.
Note: you can't rely on the HTML lang attribute or og:locale for this determination.

<meta name="locale" content="ja_JP">

Separating the SEO sitemap from the search sitemap

AI Search (Website data source) crawls via sitemap.

However, our public sitemap was intentionally excluding some languages for SEO reasons. As a result, those languages always returned zero search results.

Since we generate sitemaps with @astrojs/sitemap, we output a separate sitemap for search that includes all languages.

How are search results ordered?

It's quite different from what you might imagine from the term "AI search".

AI Search divides Japanese text into chunks of roughly 300–450 characters.
Up to 50 related chunks are picked up, and the pages containing them appear in the results.
Pages containing chunks judged to have high relevance rank higher. Since multiple chunks from a single page can be selected, the actual number of search results will be fewer than 50.

We handle page-level aggregation on the frontend side. And throughout this entire process, generative AI isn't involved at all.

Summary

Implementation requires your domain's zone to be hosted on Cloudflare and managed through Pages/Workers; however, the setup is straightforward, and I found it quite useful for cases where you want a simple, lightweight site search without much overhead.

Conversely, if you want to add search functionality without touching infrastructure, retrieve all results, or need operational features like search log analysis, suggestions, and synonym dictionaries, traditional ASP solutions are more robust.

That said, implementing a full ASP solution would be heavy-handed, but search functionality is still desired. I believe this is a highly compelling option for sites at that particular scale.