Localization & Multi-Language

# The CMS stores content per locale as a dimension, not as separate copies.
#
# When an editor opens a page in Visual Builder and switches locale,
# they are editing the same content item - just its locale variant.
# The same content key (e.g. "abc123") resolves to different field values
# depending on the locale requested.
#
# Graph exposes this through _metadata.locale:
query GetAllLocales {
  _Content(limit: 5) {
    items {
      _metadata {
        key           # same key across all locales
        locale        # "en", "fr", "de", etc.
        displayName   # locale-specific title
        url { default }
      }
    }
  }
}

# Result - same page key, two locale variants:
# { key: "abc123", locale: "en", displayName: "About Us", url: "/en/about" }
# { key: "abc123", locale: "fr", displayName: "À propos", url: "/fr/about" }

# Add a locale filter to any query to get content in a specific language.
# Use the _metadata.locale field with the 'eq' or 'in' operator.

query GetLocalizedPage($url: String!, $locale: [Locales]) {
  _Content(
    where: {
      _metadata: {
        url:    { default: { eq: $url } }
        locale: { in: $locale }          # e.g. ["fr", "fr-CA"]
      }
    }
  ) {
    items {
      _metadata { locale displayName url { default } }
      ... on LandingPage {
        headline
        body { json }
      }
    }
  }
}

# In graphqlFetch - pass locale from the request:
const locale = params.lang ?? "en";
const res = await graphqlFetch(GET_LOCALIZED_PAGE, { url, locale: [locale] });

# Fallback locale chain - request the most specific locale first,
# then progressively broader locales, then the default.
#
# If a page hasn't been translated into fr-CA yet, the fr version
# (or the en fallback) should be shown instead of a 404.
#
# Graph returns the first match from the array - ordered by specificity.

query GetPageWithFallback($url: String!) {
  _Content(
    where: {
      _metadata: {
        url:    { default: { eq: $url } }
        locale: { in: ["fr-CA", "fr", "en"] }   # ← priority order
      }
    }
    limit: 1   # only want the best match
  ) {
    items {
      _metadata { locale displayName url { default } }
      ... on LandingPage { headline body { json } }
    }
  }
}

// Build the fallback chain from the request locale in code:
function buildLocaleChain(locale: string): string[] {
  const [lang, region] = locale.split("-");
  const chain = region ? [`${lang}-${region}`, lang] : [lang];
  if (!chain.includes("en")) chain.push("en");  // always fall back to default
  return chain;
}
// buildLocaleChain("fr-CA") → ["fr-CA", "fr", "en"]