Routing, localization, and multi-sites

Implement routing, localization, and multi-sites

This walkthrough builds on the app from Render SitecoreAI content in your app, which hard-codes a single site name and language from environment variables. In this walkthrough, you replace those hard-coded values with request-time resolution, so your app can serve multiple sites and languages, and honor content-managed redirects.

The walkthrough provides code examples for Astro 7 and Go front-end applications, and it describes how to:

Fetch and cache your site list
Resolve the site from the request hostname
Resolve the locale from the request path
Fetch and evaluate redirects
Query the site dictionary
Wire resolution into your routing
Test your app

Before you begin

Complete the Render SitecoreAI content in your app and the Enable visual editing walkthroughs. This walkthrough builds directly on the app you built in the previous walkthroughs.
Review multi-site resolution, locale resolution, and redirects concepts.
This walkthrough assumes your SitecoreAI environment has at least one additional site or language configured. If you only have a single site and language, you can still follow along. Site and locale resolution will simply always resolve to your one configured value.

Fetch and cache your site list

Add a function that retrieves your environment's site list and caches it in memory, so you don't query it on every request.

Add the following to src/services/sitecoreClient.js:

// src/services/sitecoreClient.js

let siteListCache = null;

export async function fetchSiteList() {
  if (siteListCache) {
    return siteListCache;
  }

  const env = import.meta.env;
  const endpoint = env.SITECORE_EDGE_PLATFORM_URL;
  const contextId = env.SITECORE_EDGE_CONTEXT_ID;

  const query = `
    query SiteInfoCollectionQuery {
      site {
        siteInfoCollection { name hostname language }
      }
    }
  `;

  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-sitecore-contextid": contextId,
    },
    body: JSON.stringify({ query }),
  });

  const result = await response.json();

  if (result.errors) {
    throw new Error(JSON.stringify(result.errors));
  }

  siteListCache = result?.data?.site?.siteInfoCollection || [];
  return siteListCache;
}

Add the following to main.go:

// main.go

type siteInfo struct {
    Name     string `json:"name"`
    Hostname string `json:"hostname"`
    Language string `json:"language"`
}

var siteListCache []siteInfo

func fetchSiteList() ([]siteInfo, error) {
    if siteListCache != nil {
        return siteListCache, nil
    }

    endpoint := os.Getenv("SITECORE_EDGE_PLATFORM_URL")
    contextID := os.Getenv("SITECORE_EDGE_CONTEXT_ID")

    query := `
      query SiteInfoCollectionQuery {
        site {
          siteInfoCollection { name hostname language }
        }
      }
    `

    body, _ := json.Marshal(map[string]any{"query": query})
    req, _ := http.NewRequest("POST", endpoint, bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-sitecore-contextid", contextID)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result struct {
        Data struct {
            Site struct {
                SiteInfoCollection []siteInfo `json:"siteInfoCollection"`
            } `json:"site"`
        } `json:"data"`
        Errors any `json:"errors"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }
    if result.Errors != nil {
        return nil, fmt.Errorf("%v", result.Errors)
    }

    siteListCache = result.Data.Site.SiteInfoCollection
    return siteListCache, nil
}

Resolve the site from the request hostname

Add a function that matches the request's hostname against your cached site list, falling back to a configured default site.

Add the following to src/services/sitecoreClient.js:

// src/services/sitecoreClient.js

export function resolveSite(hostname, sites, defaultSiteName) {
  const match = sites.find((site) =>
    site.hostname
      .split(/\||,|;/)
      .map((h) => h.trim().toLowerCase())
      .some((h) => hostnameMatches(hostname.toLowerCase(), h))
  );

  return match || sites.find((site) => site.name === defaultSiteName);
}

function hostnameMatches(hostname, pattern) {
  if (!pattern) return false;
  const regex = new RegExp(
    "^" + pattern.replace(/\./g, "\\.").replace(/\*/g, ".*") + "$",
    "i"
  );
  return regex.test(hostname);
}

Update src/pages/[...slug].astro to resolve the site from the request instead of using a hard-coded environment variable:

---
// src/pages/[...slug].astro
import { fetchLayoutData, fetchSiteList, resolveSite } from '../services/sitecoreClient.js';

export const prerender = false;

const sites = await fetchSiteList();
const site = resolveSite(
  Astro.url.hostname,
  sites,
  import.meta.env.SITECORE_SITE_NAME
);
---

Add the following to main.go:

// main.go
import "regexp"

func resolveSite(hostname string, sites []siteInfo, defaultSiteName string) siteInfo {
    hostname = strings.ToLower(hostname)

    for _, site := range sites {
        for _, pattern := range strings.Split(site.Hostname, "|") {
            pattern = strings.ToLower(strings.TrimSpace(pattern))
            if pattern == "" {
                continue
            }
            escaped := strings.ReplaceAll(regexp.QuoteMeta(pattern), `\*`, ".*")
            if matched, _ := regexp.MatchString("^"+escaped+"$", hostname); matched {
                return site
            }
        }
    }

    for _, site := range sites {
        if site.Name == defaultSiteName {
            return site
        }
    }
    return siteInfo{}
}

Update your route handler to resolve the site from the request's Host header instead of a hard-coded environment variable:

// main.go
sites, err := fetchSiteList()
if err != nil {
    log.Fatal(err)
}
defaultSiteName := os.Getenv("SITECORE_SITE_NAME")

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    site := resolveSite(r.Host, sites, defaultSiteName)
    // ... use site.Name in place of the hard-coded site variable
})

Resolve the locale from the request path

Next, extract a locale segment from the request path (for example, /fr-fr/products), falling back to the resolved site's default language when no locale segment is present.

Add the following to src/services/sitecoreClient.js:

// src/services/sitecoreClient.js

export function resolveLocale(slugSegments, configuredLocales, defaultLocale) {
  const [first, ...rest] = slugSegments;
  const match = configuredLocales.find(
    (locale) => locale.toLowerCase() === (first || "").toLowerCase()
  );

  if (match) {
    return { locale: match, remainingSegments: rest };
  }
  return { locale: defaultLocale, remainingSegments: slugSegments };
}

Update src/pages/[...slug].astro to resolve the locale and strip it from the route path:

---
// src/pages/[...slug].astro
const configuredLocales = (import.meta.env.SITECORE_SITE_LOCALES || "en").split(",");
const slugSegments = Astro.params.slug ? Astro.params.slug.split('/') : [];
const { locale, remainingSegments } = resolveLocale(
  slugSegments,
  configuredLocales,
  site.language
);
let routePath = remainingSegments.length ? `/${remainingSegments.join('/')}` : '/';
---

Add the following to main.go:

// main.go

func resolveLocale(segments []string, configuredLocales []string, defaultLocale string) (string, []string) {
    if len(segments) == 0 {
        return defaultLocale, segments
    }
    for _, locale := range configuredLocales {
        if strings.EqualFold(locale, segments[0]) {
            return locale, segments[1:]
        }
    }
    return defaultLocale, segments
}

Update your route handler to resolve the locale and strip it from the route path:

// main.go
configuredLocales := strings.Split(os.Getenv("SITECORE_SITE_LOCALES"), ",")

segments := strings.Split(strings.Trim(r.URL.Path, "/"), "/")
locale, remaining := resolveLocale(segments, configuredLocales, site.Language)
routePath := "/" + strings.Join(remaining, "/")

Fetch and evaluate redirects

Add a function that retrieves a site's redirect rules and checks them against the current request before you fetch layout data.

Add the following to src/services/sitecoreClient.js:

// src/services/sitecoreClient.js

const redirectsCache = new Map();

export async function fetchRedirects(site) {
  if (redirectsCache.has(site)) {
    return redirectsCache.get(site);
  }

  const env = import.meta.env;
  const query = `
    query RedirectsQuery($siteName: String!) {
      site {
        siteInfo(site: $siteName) {
          redirects {
            pattern target redirectType isQueryStringPreserved isLanguagePreserved locale
          }
        }
      }
    }
  `;

  const response = await fetch(env.SITECORE_EDGE_PLATFORM_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-sitecore-contextid": env.SITECORE_EDGE_CONTEXT_ID,
    },
    body: JSON.stringify({ query, variables: { siteName: site } }),
  });

  const result = await response.json();
  const redirects = result?.data?.site?.siteInfo?.redirects || [];
  redirectsCache.set(site, redirects);
  return redirects;
}

export function matchRedirect(redirects, routePath, locale) {
  return redirects.find((redirect) => {
    if (redirect.locale && redirect.locale !== locale) {
      return false;
    }
    if (isRegex(redirect.pattern)) {
      return new RegExp(redirect.pattern, "i").test(routePath);
    }
    return redirect.pattern.replace(/\/$/, "") === routePath.replace(/\/$/, "");
  });
}

function isRegex(pattern) {
  // Simple heuristic: treat patterns with regex metacharacters as regular expressions.
  return /[()^$|[\]]/.test(pattern);
}

Apply a matched redirect in src/pages/[...slug].astro, before fetching layout data. Treat SERVER_TRANSFER as an internal rewrite rather than an HTTP redirect, so the visible URL doesn't change:

---
const redirects = await fetchRedirects(site.name);
const matched = matchRedirect(redirects, routePath, locale);

if (matched) {
  if (matched.redirectType === "SERVER_TRANSFER") {
    // Keep the visible URL the same; fetch layout data for the target instead.
    routePath = matched.target;
  } else {
    const status = matched.redirectType === "REDIRECT_301" ? 301 : 302;
    return Astro.redirect(matched.target, status);
  }
}
---

Add the following to main.go:

// main.go

type redirectRule struct {
    Pattern                 string  `json:"pattern"`
    Target                  string  `json:"target"`
    RedirectType            string  `json:"redirectType"`
    IsQueryStringPreserved  bool    `json:"isQueryStringPreserved"`
    IsLanguagePreserved     bool    `json:"isLanguagePreserved"`
    Locale                  *string `json:"locale"`
}

var redirectsCache = map[string][]redirectRule{}

func fetchRedirects(site string) ([]redirectRule, error) {
    if cached, ok := redirectsCache[site]; ok {
        return cached, nil
    }

    query := `
      query RedirectsQuery($siteName: String!) {
        site {
          siteInfo(site: $siteName) {
            redirects {
              pattern target redirectType isQueryStringPreserved isLanguagePreserved locale
            }
          }
        }
      }
    `
    body, _ := json.Marshal(map[string]any{
        "query":     query,
        "variables": map[string]any{"siteName": site},
    })
    req, _ := http.NewRequest("POST", os.Getenv("SITECORE_EDGE_PLATFORM_URL"), bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-sitecore-contextid", os.Getenv("SITECORE_EDGE_CONTEXT_ID"))

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result struct {
        Data struct {
            Site struct {
                SiteInfo struct {
                    Redirects []redirectRule `json:"redirects"`
                } `json:"siteInfo"`
            } `json:"site"`
        } `json:"data"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }

    redirectsCache[site] = result.Data.Site.SiteInfo.Redirects
    return redirectsCache[site], nil
}

func matchRedirect(redirects []redirectRule, routePath, locale string) *redirectRule {
    for _, r := range redirects {
        if r.Locale != nil && *r.Locale != locale {
            continue
        }
        if isRegex(r.Pattern) {
            if matched, _ := regexp.MatchString(r.Pattern, routePath); matched {
                return &r
            }
            continue
        }
        if strings.TrimRight(r.Pattern, "/") == strings.TrimRight(routePath, "/") {
            return &r
        }
    }
    return nil
}

func isRegex(pattern string) bool {
    return strings.ContainsAny(pattern, "()^$|[]")
}

Apply a matched redirect in your route handler, before fetching layout data. Treat SERVER_TRANSFER as an internal rewrite rather than an HTTP redirect, so the visible URL doesn't change:

// main.go
redirects, err := fetchRedirects(site.Name)
if err == nil {
    if matched := matchRedirect(redirects, routePath, locale); matched != nil {
        if matched.RedirectType == "SERVER_TRANSFER" {
            // Keep the visible URL the same; fetch layout data for the target instead.
            routePath = matched.Target
        } else {
            status := http.StatusFound
            if matched.RedirectType == "REDIRECT_301" {
                status = http.StatusMovedPermanently
            }
            http.Redirect(w, r, matched.Target, status)
            return
        }
    }
}

Note

These matching functions are simplified for the walkthrough. Refer to redirects for the full evaluation logic, including capture-group substitution in regex targets, the $siteLang token, and query string/locale preservation.

Query the site dictionary

Fetch the site dictionary for the resolved site and locale, so components can look up translated UI strings alongside page content.

Add the following to src/services/sitecoreClient.js:

// src/services/sitecoreClient.js
const dictionaryCache = new Map();

export async function fetchDictionary(site, language) {
  const cacheKey = `${site}:${language}`;
  if (dictionaryCache.has(cacheKey)) {
    return dictionaryCache.get(cacheKey);
  }

  const env = import.meta.env;
  const dictionary = {};
  let after = null;
  let hasNext = true;

  while (hasNext) {
    const response = await fetch(env.SITECORE_EDGE_PLATFORM_URL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-sitecore-contextid": env.SITECORE_EDGE_CONTEXT_ID,
      },
      body: JSON.stringify({
        query: `query($siteName: String!, $language: String!, $after: String) {
          site {
            siteInfo(site: $siteName) {
              dictionary(language: $language, first: 100, after: $after) {
                results { key value }
                pageInfo { endCursor hasNext }
              }
            }
          }
        }`,
        variables: { siteName: site, language, after },
      }),
    });

    const { data } = await response.json();
    const page = data.site.siteInfo.dictionary;
    for (const entry of page.results) {
      dictionary[entry.key] = entry.value;
    }
    hasNext = page.pageInfo.hasNext;
    after = page.pageInfo.endCursor;
  }

  dictionaryCache.set(cacheKey, dictionary);
  return dictionary;
}

Fetch it in src/pages/[...slug].astro, alongside your layout data:
--- const dictionary = await fetchDictionary(site.name, locale); ---
The sample components built in the previous walkthrough don't read any dictionary keys, so this walkthrough doesn't wire dictionary further. In your own app, pass it to your layout/component rendering so components can look up translated strings by key.

Add the following to main.go:

// main.go
var dictionaryCache = map[string]map[string]string{}

func fetchDictionary(site, language string) (map[string]string, error) {
    cacheKey := site + ":" + language
    if cached, ok := dictionaryCache[cacheKey]; ok {
        return cached, nil
    }

    dictionary := map[string]string{}
    var after *string

    for {
        body, _ := json.Marshal(map[string]interface{}{
            "query": `query($siteName: String!, $language: String!, $after: String) {
                site {
                    siteInfo(site: $siteName) {
                        dictionary(language: $language, first: 100, after: $after) {
                            results { key value }
                            pageInfo { endCursor hasNext }
                        }
                    }
                }
            }`,
            "variables": map[string]interface{}{"siteName": site, "language": language, "after": after},
        })
        req, _ := http.NewRequest("POST", os.Getenv("SITECORE_EDGE_PLATFORM_URL"), bytes.NewReader(body))
        req.Header.Set("Content-Type", "application/json")
        req.Header.Set("x-sitecore-contextid", os.Getenv("SITECORE_EDGE_CONTEXT_ID"))

        resp, err := http.DefaultClient.Do(req)
        if err != nil {
            return nil, err
        }
        defer resp.Body.Close()

        var result struct {
            Data struct {
                Site struct {
                    SiteInfo struct {
                        Dictionary struct {
                            Results []struct {
                                Key   string `json:"key"`
                                Value string `json:"value"`
                            } `json:"results"`
                            PageInfo struct {
                                EndCursor string `json:"endCursor"`
                                HasNext   bool   `json:"hasNext"`
                            } `json:"pageInfo"`
                        } `json:"dictionary"`
                    } `json:"siteInfo"`
                } `json:"site"`
            } `json:"data"`
        }
        if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
            return nil, err
        }

        page := result.Data.Site.SiteInfo.Dictionary
        for _, entry := range page.Results {
            dictionary[entry.Key] = entry.Value
        }
        if !page.PageInfo.HasNext {
            break
        }
        after = &page.PageInfo.EndCursor
    }

    dictionaryCache[cacheKey] = dictionary
    return dictionary, nil
}

Call it in your route handler, alongside fetching layout data. The sample components built in the previous walkthrough don't read any dictionary keys, so this walkthrough doesn't wire the result further. In your own app, pass it through to your component renderer so components can look up translated strings by key.

Note

If your framework supports static site generation, you can enumerate every page for a site and language up front using the routes query, instead of resolving one path at a time as requests come in.

Wire resolution into your routing

With site, locale, and redirect resolution in place, update the call to fetchLayoutData to use the resolved site name and locale instead of the hard-coded environment variables from the previous walkthrough:

---
// src/pages/[...slug].astro
let layoutData;
try {
  layoutData = await fetchLayoutData(site.name, locale, routePath);
} catch (error) {
  return Astro.redirect('/404');
}

if (!layoutData) {
  return Astro.redirect('/404'); // Sitecore returned null; the route doesn't exist.
}
---

// main.go
data, err := fetchLayoutData(site.Name, locale, routePath)
if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return
}
if data == nil {
    http.Redirect(w, r, "/404", http.StatusFound) // Sitecore returned null; the route doesn't exist.
    return
}

Test your app

This walkthrough's resolveLocale validates the URL's locale segment against your app's configured locale list, so add the new locale to your .env file's list (for example, SITECORE_SITE_LOCALES=en,fr-fr) as a one-time setup step, matching a language your SitecoreAI site is available in.
Restart your development server.
Request the root path with a locale segment, such as /fr-fr, and confirm the layout data returned reflects that language.
If your environment has more than one site configured, test with a hostname that matches a non-default site (for example, by editing your local hosts file), and confirm the correct site's content is returned.
Ask a content author to add a test redirect rule to your site's redirect map (or add one yourself, using the Content Editor), then request the redirect's source path and confirm your app redirects as expected.
Confirm the site dictionary is populated by temporarily logging the resolved dictionary object, and check that a known key returns its expected translated value.

Next steps

If you run into issues, see Troubleshooting.

If you have suggestions for improving this article, let us know!