feat(core): TRAC-421 consume merchant-configured locale subfolders from BC backend (bigcommerce#3015)

Author: mfaris9

.changeset/trac-421-custom-locale-subfolders.md

@@ -0,0 +1,5 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Consume merchant-configured per-locale URL subfolders from the BigCommerce Storefront GraphQL API (`Locale.path`). The locale that sits at the bare root URL (`/`) is derived from the CP configuration: if the default locale has no path, it sits at root; otherwise, if exactly one non-default locale has no path, that one sits at root; otherwise every locale gets a prefix. Locales with a path use it; locales without a path fall back to their locale code.

core/build-config/schema.ts

@@ -5,6 +5,7 @@ export const buildConfigSchema = z.object({
     z.object({
       code: z.string(),
       isDefault: z.boolean(),
+      path: z.string().nullable(),
     }),
   ),
   urls: z.object({

core/i18n/locales.ts

@@ -1,6 +1,33 @@
 import { buildConfig } from '~/build-config/reader';
 
 const localeNodes = buildConfig.get('locales');
+const defaultLocaleNode = localeNodes.find((locale) => locale.isDefault);
 
 export const locales = localeNodes.map((locale) => locale.code);
-export const defaultLocale = localeNodes.find((locale) => locale.isDefault)?.code ?? 'en';
+export const defaultLocale = defaultLocaleNode?.code ?? 'en';
+
+export const prefixes = localeNodes.reduce<Record<string, `/${string}`>>((acc, locale) => {
+  if (locale.path) acc[locale.code] = `/${locale.path}`;
+
+  return acc;
+}, {});
+
+// The locale that should occupy the bare root URL ("/").
+//
+// Rule:
+//   1. If the default locale has no CP path, default lives at "/".
+//   2. Else, if exactly one non-default locale has no CP path, that one lives at "/".
+//   3. Otherwise, no locale lives at "/" and every locale gets a prefix.
+function computeRootLocale(): string | null {
+  if (!defaultLocaleNode) return defaultLocale;
+  if (!defaultLocaleNode.path) return defaultLocaleNode.code;
+
+  const blankNonDefaults = localeNodes.filter((locale) => !locale.isDefault && !locale.path);
+  const [onlyBlank, ...rest] = blankNonDefaults;
+
+  if (onlyBlank && rest.length === 0) return onlyBlank.code;
+
+  return null;
+}
+
+export const rootLocale = computeRootLocale();

core/i18n/routing.ts

@@ -1,21 +1,28 @@
 import { createNavigation } from 'next-intl/navigation';
 import { defineRouting } from 'next-intl/routing';
 
-import { defaultLocale, locales } from './locales';
+import { defaultLocale, locales, prefixes, rootLocale } from './locales';
 
 enum LocalePrefixes {
   ALWAYS = 'always',
-  // Don't use NEVER as there is a issue that causes cache problems and returns the wrong messages.
+  // Don't use NEVER as there is an issue that causes cache problems and returns the wrong messages.
   // More info: https://github.com/amannn/next-intl/issues/786
   // NEVER = 'never',
   ASNEEDED = 'as-needed', // removes prefix on default locale
 }
 
-const localePrefix = LocalePrefixes.ASNEEDED;
+// `rootLocale` is the locale (if any) that occupies the bare "/" URL. We hand it
+// to next-intl as the routing default so URLs like "/" resolve correctly. When no
+// locale lives at "/", every locale needs a prefix, so we use `always` mode and
+// fall back to the BC default for next-intl's defaultLocale.
+const localePrefix =
+  rootLocale === null
+    ? { mode: LocalePrefixes.ALWAYS, prefixes }
+    : { mode: LocalePrefixes.ASNEEDED, prefixes };
 
 export const routing = defineRouting({
   locales,
-  defaultLocale,
+  defaultLocale: rootLocale ?? defaultLocale,
   localePrefix,
 });
 

core/lib/seo/canonical.ts

@@ -3,7 +3,7 @@ import { cache } from 'react';
 import { client } from '~/client';
 import { graphql } from '~/client/graphql';
 import { revalidate } from '~/client/revalidate-target';
-import { defaultLocale, locales } from '~/i18n/locales';
+import { defaultLocale, locales, prefixes, rootLocale } from '~/i18n/locales';
 
 interface CanonicalUrlOptions {
   /**
@@ -90,7 +90,10 @@ function buildLocalizedUrl(baseUrl: string, pathname: string, locale: string): s
 
   const url = new URL(pathname, baseUrl);
 
-  url.pathname = locale === defaultLocale ? url.pathname : `/${locale}${url.pathname}`;
+  const prefix = prefixes[locale] ?? `/${locale}`;
+  const skipPrefix = locale === rootLocale;
+
+  url.pathname = skipPrefix ? url.pathname : `${prefix}${url.pathname}`;
 
   if (trailingSlash && !url.pathname.endsWith('/')) {
     url.pathname += '/';

core/next.config.ts

@@ -25,6 +25,7 @@ const SettingsQuery = graphql(`
         locales {
           code
           isDefault
+          path
         }
       }
     }

core/proxies/with-routes.ts

@@ -5,6 +5,7 @@ import { auth } from '~/auth';
 import { client } from '~/client';
 import { graphql } from '~/client/graphql';
 import { revalidate } from '~/client/revalidate-target';
+import { prefixes } from '~/i18n/locales';
 import { getVisitIdCookie, getVisitorIdCookie } from '~/lib/analytics/bigcommerce';
 import { sendProductViewedEvent } from '~/lib/analytics/bigcommerce/data-events';
 import { kvKey, STORE_STATUS_KEY } from '~/lib/kv/keys';
@@ -218,12 +219,14 @@ const updateStatusCache = async (
 };
 
 const clearLocaleFromPath = (path: string, locale: string) => {
-  if (path === `/${locale}` || path === `/${locale}/`) {
+  const prefix = prefixes[locale] ?? `/${locale}`;
+
+  if (path === prefix || path === `${prefix}/`) {
     return '/';
   }
 
-  if (path.startsWith(`/${locale}/`)) {
-    return path.replace(`/${locale}`, '');
+  if (path.startsWith(`${prefix}/`)) {
+    return path.replace(prefix, '');
   }
 
   return path;