fix: implement localized routes penality

Author: logaretm

packages/nextjs/src/client/routing/parameterization.ts

@@ -37,6 +37,16 @@ function getRouteSpecificity(routePath: string): number {
     // Static segments add 0 to score as they are most specific
   }
 
+  if (segments.length > 0) {
+    // Add a small penalty based on inverse of segment count
+    // This ensures that routes with more segments are preferred
+    // e.g., '/:locale/foo' is more specific than '/:locale'
+    // We use a small value (1 / segments.length) so it doesn't override the main scoring
+    // but breaks ties between routes with the same number of dynamic segments
+    const segmentCountPenalty = 1 / segments.length;
+    score += segmentCountPenalty;
+  }
+
   return score;
 }
 
@@ -134,6 +144,23 @@ function findMatchingRoutes(
     }
   }
 
+  // Try matching with optional prefix segments (for i18n routing patterns)
+  // This handles cases like '/foo' matching '/:locale/foo' when using next-intl with localePrefix: "as-needed"
+  // We do this regardless of whether we found direct matches, as we want the most specific match
+  if (!route.startsWith('/:')) {
+    for (const dynamicRoute of dynamicRoutes) {
+      if (dynamicRoute.hasOptionalPrefix && dynamicRoute.regex) {
+        // Prepend a placeholder segment to simulate the optional prefix
+        // e.g., '/foo' becomes '/PLACEHOLDER/foo' to match '/:locale/foo'
+        const routeWithPrefix = `/SENTRY_OPTIONAL_PREFIX${route}`;
+        const regex = getCompiledRegex(dynamicRoute.regex);
+        if (regex?.test(routeWithPrefix)) {
+          matches.push(dynamicRoute.path);
+        }
+      }
+    }
+  }
+
   return matches;
 }
 

packages/nextjs/src/config/manifest/createRouteManifest.ts

@@ -47,7 +47,11 @@ function getDynamicRouteSegment(name: string): string {
   return `:${name.slice(1, -1)}`;
 }
 
-function buildRegexForDynamicRoute(routePath: string): { regex: string; paramNames: string[] } {
+function buildRegexForDynamicRoute(routePath: string): {
+  regex: string;
+  paramNames: string[];
+  hasOptionalPrefix: boolean;
+} {
   const segments = routePath.split('/').filter(Boolean);
   const regexSegments: string[] = [];
   const paramNames: string[] = [];
@@ -95,7 +99,13 @@ function buildRegexForDynamicRoute(routePath: string): { regex: string; paramNam
     pattern = `^/${regexSegments.join('/')}$`;
   }
 
-  return { regex: pattern, paramNames };
+  // Detect if the first parameter is a common i18n prefix segment
+  // Common patterns: locale, lang, language
+  const firstParam = paramNames[0];
+  const hasOptionalPrefix =
+    firstParam !== undefined && (firstParam === 'locale' || firstParam === 'lang' || firstParam === 'language');
+
+  return { regex: pattern, paramNames, hasOptionalPrefix };
 }
 
 function scanAppDirectory(
@@ -116,11 +126,12 @@ function scanAppDirectory(
       const isDynamic = routePath.includes(':');
 
       if (isDynamic) {
-        const { regex, paramNames } = buildRegexForDynamicRoute(routePath);
+        const { regex, paramNames, hasOptionalPrefix } = buildRegexForDynamicRoute(routePath);
         dynamicRoutes.push({
           path: routePath,
           regex,
           paramNames,
+          hasOptionalPrefix,
         });
       } else {
         staticRoutes.push({

packages/nextjs/src/config/manifest/types.ts

@@ -14,6 +14,11 @@ export type RouteInfo = {
    * (Optional) The names of dynamic parameters in the route
    */
   paramNames?: string[];
+  /**
+   * (Optional) Indicates if the first segment is an optional prefix (e.g., for i18n routing)
+   * When true, routes like '/foo' should match '/:locale/foo' patterns
+   */
+  hasOptionalPrefix?: boolean;
 };
 
 /**