feat(experimental): opt-in localeAgnosticDefaultRoutes route-name resolution (PoC)

[Togetic]

⚠️ Proof of concept / RFC — not intended to merge as-is. It opens the design discussion for #4016 with concrete code; the API is deliberately minimal and I'm happy to reshape it.

🔗 Linked issue

Part of #4016

📚 Description

Adds an opt-in experimental.localeAgnosticDefaultRoutes flag that, under strategy: 'prefix_except_default', makes createLocaleRouteNameGetter resolve the default locale to the locale-agnostic ___default route name instead of the build-bound <base>___<defaultLocale>.

Why: to serve a single build across regions whose default locale is chosen at runtime, the default-locale route tree must be addressable by a locale-agnostic name (<base>___default). The build side can be done from a module (pages:resolved rename), but the runtime name getter hardcodes <base>___<locale> for prefix_except_default with no seam to influence it — so consumers are forced to patch dist/. This gives that behavior a supported home.

Scope (deliberately minimal):

• New flag wired exactly like experimental.compactRoutes (src/types.ts, src/constants.ts, the src/bundler.ts define, src/env.d.ts).
• createLocaleRouteNameGetter: under the flag + prefix_except_default, the default locale → normalizeRouteName(name) + defaultRouteNameSuffix; non-default locales unchanged.
• Off by default → zero behavior change when unset.

Not in this PoC (discussion in #4016): generating the ___default tree natively (so no companion module is needed), reading the default locale from runtime config, and the locale-detection fallback.

✅ Verification

• pnpm test:types, pnpm lint, and pnpm test:unit all pass.
• Added 2 unit tests in test/routing-utils.test.ts covering flag-on resolution (default locale → route1___default, non-default → route1___fr); existing getter tests unchanged.

📝 Notes

The behavior here mirrors a dist/ patch that has been running in production (single image, multiple regions). This PR is about giving it a supported, opt-in home and starting the API conversation rather than landing a finished feature.

Summary by CodeRabbit

• New Features

  • Added support for locale-agnostic default routes when using the default-locale prefix routing mode.
  • Default-locale routes can now resolve to a shared ___default path while other locales continue to use localized routes.

• Bug Fixes

  • Improved route-name resolution for default locales in mixed locale routing setups.

• Tests

  • Expanded routing coverage for the new default-route behavior.

[coderabbitai]

Walkthrough

A new experimental option localeAgnosticDefaultRoutes (boolean, default false) is added to ExperimentalFeatures, DEFAULT_OPTIONS, and the bundler's define config as __I18N_LOCALE_AGNOSTIC_DEFAULT_ROUTES__. The runtime createLocaleRouteNameGetter gains a new branch: when this flag is enabled under the prefix_except_default strategy, the default locale resolves to a locale-agnostic route name using defaultRouteNameSuffix, while non-default locales continue using getLocalizedRouteName. Tests and the global test stub are updated accordingly.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main experimental change: opt-in locale-agnostic default route-name resolution as a proof of concept.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/runtime/routing/utils.ts`:
- Around line 25-33: The default-locale route naming is inconsistent between
runtime and generation for prefix_except_default. Update the route name emission
in src/routing.ts so it uses the same locale-agnostic suffix as utils.ts (via
normalizeRouteName, getLocalizedRouteName, and defaultRouteNameSuffix) when
experimental.localeAgnosticDefaultRoutes is enabled, ensuring both sides resolve
the default locale to the same <name>___default form.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: e103db93-f409-4ea7-930f-618ed7db5d70

📥 Commits

Reviewing files that changed from the base of the PR and between bd54cb9 and 07e80be.

📒 Files selected for processing (7)

• src/bundler.ts
• src/constants.ts
• src/env.d.ts
• src/runtime/routing/utils.ts
• src/types.ts
• test/routing-utils.test.ts
• test/setup.ts