feat: Implement route-based culture support in localization. by maliming · Pull Request #25174 · abpframework/abp

maliming · 2026-03-30T03:18:58Z

Add URL-based localization support that embeds the culture code directly in the URL path (e.g. /tr/identity/users). Enabled with a single configuration:

Configure<AbpRequestLocalizationOptions>(options =>
{
    options.UseRouteBasedCulture = true;
});

When enabled, ABP automatically handles route registration, URL generation, menu links, and language switching for MVC, Razor Pages, Blazor Server, and Blazor WebApp (WASM).

For Blazor pages, @page "/{culture}/..." route variants need to be added manually. All ABP built-in module pages already include these routes.

Related PRs:

volosoft/volo#22040
volosoft/lepton#3446
Add URL-based localization sample abp-samples#312

Documentation:

Notes for the Angular team

A new boolean field useRouteBasedCulture has been added to the /api/abp/application-configuration response, under the localization object:

{
  "localization": {
    "useRouteBasedCulture": true,
    ...
  }
}

This flag indicates that the server has UseRouteBasedCulture = true configured. When this flag is true, the Angular app should:

Prefix all routes with /:culture — Add a /:culture parent route segment so that URLs like /tr/identity/users are routed correctly.
Update the language switcher — Instead of only calling sessionState.setLanguage(cultureName), also navigate to the same page under the new culture prefix (e.g. /tr/identity/users → /en/identity/users).
Update internal navigation calls — Any router.navigate() call that produces an absolute path (e.g. router.navigate(['/identity/security-logs'])) should prepend the current culture segment when useRouteBasedCulture is true.

No API endpoint changes are needed — routes like /api/... are unaffected.

…d add tests

…zation examples

…r to use CurrentCulture instead of CurrentUICulture

…tenant management pages for URL-based localization

…and enhance menu item URL handling

…oved URL handling and culture prefixing

…estCultureProvider after QueryStringRequestCultureProvider

…turePrefixHelper and adding browser check

…calization handling

…d tests

github-actions · 2026-04-01T04:10:37Z

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 79.4%, saving 896.5 KB.

Filename	Before	After	Improvement	Visual comparison
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/cover.png`	1.1 MB	232.4 KB	79.4%	View diff

…l examples and images

github-actions · 2026-04-01T07:07:44Z

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 71.8%, saving 1.4 MB.

Filename	Before	After	Improvement	Visual comparison
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-en.png`	455.8 KB	98.0 KB	78.5%	View diff
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-tr.png`	442.7 KB	97.9 KB	77.9%	View diff
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/blazor-webapp-tr.png`	379.3 KB	82.2 KB	78.3%	View diff
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/blazor-server-zh-hans.png`	352.6 KB	83.5 KB	76.3%	View diff
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/module-identity-users.png`	191.9 KB	37.7 KB	80.3%	View diff
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/cover.png`	232.4 KB	180.0 KB	22.5%	View diff

…text and update route order for Razor Pages

…ork/abp into feature/url-based-localization

github-actions · 2026-04-01T07:10:40Z

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 9.7%, saving 40.0 KB.

Filename	Before	After	Improvement	Visual comparison
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/cover.png`	180.0 KB	153.9 KB	14.5%	View diff
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-en.png`	98.0 KB	92.4 KB	5.7%	View diff
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-tr.png`	97.9 KB	93.0 KB	5.0%	View diff
`docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/module-identity-users.png`	37.7 KB	34.3 KB	9.0%	View diff

2 images did not require optimisation.

…c methods

…r for improved culture prefix handling

Copilot

Pull request overview

Implements opt-in route-based culture support (e.g. /tr/...) across ABP’s localization pipeline, including automatic routing, URL generation, menu URL rewriting, and Blazor theme behavior.

Changes:

Adds UseRouteBasedCulture to AbpRequestLocalizationOptions and wires it into request culture providers + MVC/Razor Pages routing and URL generation.
Introduces menu URL provider infrastructure and culture-prefix providers for MVC/Blazor Server and Blazor WASM.
Updates built-in Blazor module pages/themes and adds comprehensive tests + documentation for the feature.

Reviewed changes

Copilot reviewed 61 out of 67 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
modules/tenant-management/src/Volo.Abp.TenantManagement.Blazor/Pages/TenantManagement/TenantManagement.razor.cs	Adds `Culture` route parameter binding.
modules/tenant-management/src/Volo.Abp.TenantManagement.Blazor/Pages/TenantManagement/TenantManagement.razor	Adds culture-prefixed `@page` route.
modules/setting-management/src/Volo.Abp.SettingManagement.Blazor/Pages/SettingManagement/SettingManagement.razor.cs	Adds `Culture` route parameter binding.
modules/setting-management/src/Volo.Abp.SettingManagement.Blazor/Pages/SettingManagement/SettingManagement.razor	Adds culture-prefixed `@page` route.
modules/identity/src/Volo.Abp.Identity.Blazor/Pages/Identity/UserManagement.razor.cs	Adds `Culture` route parameter binding.
modules/identity/src/Volo.Abp.Identity.Blazor/Pages/Identity/UserManagement.razor	Adds culture-prefixed `@page` route.
modules/identity/src/Volo.Abp.Identity.Blazor/Pages/Identity/RoleManagement.razor.cs	Adds `Culture` route parameter binding.
modules/identity/src/Volo.Abp.Identity.Blazor/Pages/Identity/RoleManagement.razor	Adds culture-prefixed `@page` route.
modules/basic-theme/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme/Themes/Basic/WebAssemblyRedirectToLogin.razor	Makes login redirect culture-aware in WASM.
modules/basic-theme/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme/Themes/Basic/LoginDisplay.razor.cs	Culture-aware login/logout URLs; navigation tweaks.
modules/basic-theme/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme/Themes/Basic/LoginDisplay.razor	Uses computed culture-aware login URL.
modules/basic-theme/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme/Themes/Basic/LanguageSwitch.razor	Adds route-culture navigation for language switching.
modules/basic-theme/src/Volo.Abp.AspNetCore.Components.WebAssembly.BasicTheme/BasicThemeToolbarContributor.cs	Reorders toolbar items (LoginDisplay before LanguageSwitch).
modules/basic-theme/src/Volo.Abp.AspNetCore.Components.Server.BasicTheme/Themes/Basic/LoginDisplay.razor.cs	Builds login link using route-culture (server).
modules/basic-theme/src/Volo.Abp.AspNetCore.Components.Server.BasicTheme/Themes/Basic/LoginDisplay.razor	Uses `GetLoginUrl()` for login link.
modules/account/src/Volo.Abp.Account.Blazor/Pages/Account/AccountManage.razor.cs	Adds `Culture` route parameter binding.
modules/account/src/Volo.Abp.Account.Blazor/Pages/Account/AccountManage.razor	Adds culture-prefixed `@page` route.
modules/account/src/Volo.Abp.Account.Blazor/AbpAccountBlazorUserMenuContributor.cs	Switches menu URL to `~/...` form (for prefixing).
framework/test/Volo.Abp.AspNetCore.Tests/Volo/Abp/AspNetCore/Localization/RouteBasedCultureTestModule.cs	Test module enabling route-based culture.
framework/test/Volo.Abp.AspNetCore.Tests/Volo/Abp/AspNetCore/Localization/RouteBasedCulture_Tests.cs	Verifies culture selection + cookie behavior.
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/Localization/RouteBasedCultureUrlHelper_Tests.cs	Tests culture-prefixing URL helper (WASM).
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/Localization/RouteBasedCultureNavigationHelper_Tests.cs	Tests route-culture navigation helper behavior.
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/Localization/RouteBasedCultureApiRouting_Tests.cs	Ensures API routing not intercepted by culture routes.
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/Localization/LanguageSwitchRouteCultureReplacement_Tests.cs	Tests returnUrl culture replacement (route + query).
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/Localization/AbpLanguagesController_Tests.cs	Tests `/Abp/Languages/Switch` route-culture replacement.
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/Localization/AbpCultureMenuItemUrlProvider_Tests.cs	Tests menu URL culture prefixing provider.
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/Localization/AbpCultureAwareUrlHelper_Tests.cs	Tests URL helper culture injection wrapper/factory.
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo/Abp/AspNetCore/Mvc/AbpAspNetCoreMvcTestModule.cs	Enables route-based culture in MVC test host.
framework/test/Volo.Abp.AspNetCore.Mvc.Tests/Volo.Abp.AspNetCore.Mvc.Tests.csproj	Adds reference needed for WASM helpers in tests.
framework/src/Volo.Abp.UI.Navigation/Volo/Abp/Ui/Navigation/MenuManager.cs	Runs URL providers after menu configuration.
framework/src/Volo.Abp.UI.Navigation/Volo/Abp/Ui/Navigation/MenuItemUrlProviderContext.cs	Adds context object for URL providers.
framework/src/Volo.Abp.UI.Navigation/Volo/Abp/Ui/Navigation/MenuItemCulturePrefixHelper.cs	Adds recursive URL prefix helper for menus.
framework/src/Volo.Abp.UI.Navigation/Volo/Abp/Ui/Navigation/IMenuItemUrlProvider.cs	Introduces post-processing hook for menu item URLs.
framework/src/Volo.Abp.UI.Navigation/Volo/Abp/Ui/Navigation/IMenuItemCulturePrefixHelper.cs	Interface for menu culture-prefix helper.
framework/src/Volo.Abp.AspNetCore/Microsoft/AspNetCore/RequestLocalization/DefaultAbpRequestLocalizationOptionsProvider.cs	Inserts `RouteDataRequestCultureProvider` when enabled.
framework/src/Volo.Abp.AspNetCore/Microsoft/AspNetCore/RequestLocalization/AbpRequestLocalizationOptions.cs	Adds `UseRouteBasedCulture` option.
framework/src/Volo.Abp.AspNetCore/Microsoft/AspNetCore/RequestLocalization/AbpRequestLocalizationMiddleware.cs	Persists culture + HasRouteCulture cookie for Blazor SSR.
framework/src/Volo.Abp.AspNetCore/Microsoft/AspNetCore/RequestLocalization/AbpRequestCultureCookieHelper.cs	Adds HasRouteCulture cookie + route-culture helper.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/Localization/QueryStringCultureReplacementContext.cs	Adds `CurrentCulture` for smarter replacement.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/Localization/AbpLanguagesController.cs	Uses cookie-derived current culture for returnUrl replacement.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/Localization/AbpCultureRouteUrlHelperFactory.cs	Wraps URL helper factory to inject culture route values.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/Localization/AbpCultureRoutePagesConvention.cs	Adds `{culture}` selector to Razor Pages routes.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/Localization/AbpCultureRouteConstraint.cs	Adds culture constraint based on configured languages.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/Localization/AbpCultureMenuItemUrlProvider.cs	Prefixes menu URLs with culture when enabled.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/Localization/AbpCultureAwareUrlHelper.cs	Wraps `IUrlHelper` to auto-inject culture values.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/Localization/AbpAspNetCoreMvcQueryStringCultureReplacement.cs	Replaces route-culture + query-string culture values in returnUrl.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/ApplicationConfigurations/AbpApplicationConfigurationAppService.cs	Exposes `UseRouteBasedCulture` via app configuration DTO.
framework/src/Volo.Abp.AspNetCore.Mvc/Volo/Abp/AspNetCore/Mvc/AbpAspNetCoreMvcModule.cs	Registers route constraint, MVC culture route, pages convention, URL helper factory.
framework/src/Volo.Abp.AspNetCore.Mvc.Contracts/Volo/Abp/AspNetCore/Mvc/ApplicationConfigurations/ApplicationLocalizationConfigurationDto.cs	Adds `UseRouteBasedCulture` field.
framework/src/Volo.Abp.AspNetCore.Components.WebAssembly/Volo/Abp/AspNetCore/Components/WebAssembly/RouteBasedCultureUrlHelper.cs	Adds culture-prefix URL helper for WASM.
framework/src/Volo.Abp.AspNetCore.Components.WebAssembly/Volo/Abp/AspNetCore/Components/WebAssembly/RouteBasedCultureNavigationHelper.cs	Adds culture-switch navigation helper for WASM.
framework/src/Volo.Abp.AspNetCore.Components.WebAssembly/Volo/Abp/AspNetCore/Components/WebAssembly/IRouteBasedCultureUrlHelper.cs	Interface for WASM culture-prefix URL helper.
framework/src/Volo.Abp.AspNetCore.Components.WebAssembly/Volo/Abp/AspNetCore/Components/WebAssembly/IRouteBasedCultureNavigationHelper.cs	Interface for WASM culture-switch navigation helper.
framework/src/Volo.Abp.AspNetCore.Components.WebAssembly.Theming/Volo.Abp.AspNetCore.Components.WebAssembly.Theming.csproj	Adds authentication package dependency for theming helpers.
framework/src/Volo.Abp.AspNetCore.Components.WebAssembly.Theming/CultureAwareRedirectToLoginHelper.cs	Centralizes culture-aware redirect-to-login logic.
framework/src/Volo.Abp.AspNetCore.Components.WebAssembly.Theming/CultureAwareAuthenticationBase.cs	Base class for culture-aware WASM authentication pages.
framework/src/Volo.Abp.AspNetCore.Components.WebAssembly.Theming/AbpWasmCultureMenuItemUrlProvider.cs	Prefixes menu URLs with culture in WASM (browser-only).
docs/en/framework/fundamentals/url-based-localization.md	Adds full documentation for URL-based localization.
docs/en/framework/fundamentals/localization.md	Links to URL-based localization doc.
docs/en/framework/fundamentals/index.md	Adds URL-based localization to fundamentals index.
docs/en/Community-Articles/2026-03-29-Url-Based-Localization/POST.md	Adds community article describing feature and usage.
docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/module-identity-users.png	Adds documentation image asset.

…ration

github-actions · 2026-04-03T05:59:17Z

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 79.1%, saving 401.6 KB.

Filename	Before	After	Improvement	Visual comparison
`docs/en/images/url-based-localization-angular-routes.png`	355.1 KB	80.9 KB	77.2%	View diff
`docs/en/images/url-based-localization-angular-menu-url.png`	152.6 KB	25.2 KB	83.5%	View diff

6 images did not require optimisation.

sumeyyeKurtulus · 2026-04-03T06:04:29Z

Hello @fahrigedik I have just updated the Angular part for this implementation. I have also created a PR for the lepton-x theme https://github.com/volosoft/lepton/pull/3451. That would be the best if you could review the code 🙏🏻

gizemmutukurt · 2026-04-06T05:04:22Z

https://github.com/volosoft/volo/pull/22040#issuecomment-4190434066

maliming added 7 commits March 29, 2026 17:50

feat: Implement route-based culture support in localization.

dc3e633

feat: Enhance URL-based localization support for Blazor components an…

6f15b2f

…d add tests

refactor: Remove unnecessary Blazor web app configuration from locali…

7d2686d

…zation examples

fix: Update fallback culture handling in AbpCultureMenuItemUrlProvide…

0292b2b

…r to use CurrentCulture instead of CurrentUICulture

feat: Add culture parameter to account, identity, user, setting, and …

cd47809

…tenant management pages for URL-based localization

feat: Implement URL-based localization support for Blazor components …

0880b23

…and enhance menu item URL handling

feat: Refactor LoginDisplay and BasicThemeToolbarContributor for impr…

0d239d4

…oved URL handling and culture prefixing

maliming added this to the 10.3-preview milestone Mar 30, 2026

maliming added 2 commits March 30, 2026 15:49

feat: Enhance route-based culture handling by inserting RouteDataRequ…

c36823f

…estCultureProvider after QueryStringRequestCultureProvider

feat: Refactor culture prefix handling by moving logic to MenuItemCul…

bb78038

…turePrefixHelper and adding browser check

skoc10 modified the milestones: 10.3-preview, 10.3-final Mar 31, 2026

feat: Implement route-based culture navigation helper for improved lo…

5559596

…calization handling

skoc10 changed the base branch from dev to rel-10.3 March 31, 2026 11:53

maliming modified the milestones: 10.3-final, 10.3-preview Mar 31, 2026

maliming marked this pull request as ready for review April 1, 2026 02:20

maliming and others added 2 commits April 1, 2026 12:09

feat: Add route-based culture support with custom route constraint an…

5525449

…d tests

Optimised images with calibre/image-actions

3a16c04

maliming and others added 2 commits April 1, 2026 15:06

feat: Enhance documentation for URL-based localization with additiona…

cb41228

…l examples and images

Optimised images with calibre/image-actions

209c907

maliming and others added 3 commits April 1, 2026 15:09

fix: Adjust route constraint to handle URL generation without HttpCon…

299b428

…text and update route order for Razor Pages

Merge branch 'feature/url-based-localization' of github.com:abpframew…

e2e6f04

…ork/abp into feature/url-based-localization

Optimised images with calibre/image-actions

ceede87

maliming added 3 commits April 1, 2026 16:22

feat: Implement URL-based culture handling in Blazor and MVC requests

420c860

feat: Enhance URL-based culture handling with new interfaces and asyn…

6895d24

…c methods

feat: Add MenuItemCulturePrefixHelper to AbpCultureMenuItemUrlProvide…

2bbf8d6

…r for improved culture prefix handling

feat: Implement route-based culture handling with new helpers and tests

c98a08b

Copilot AI review requested due to automatic review settings April 2, 2026 05:02

Copilot started reviewing on behalf of maliming April 2, 2026 05:03 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

maliming requested a review from EngincanV April 2, 2026 05:28

sumeyyeKurtulus self-assigned this Apr 2, 2026

EngincanV approved these changes Apr 2, 2026

View reviewed changes

EngincanV requested a review from gizemmutukurt April 2, 2026 07:56

sumeyyeKurtulus and others added 8 commits April 3, 2026 08:55

update: dynamic layout for url matching

bd86923

update: permission guard to find the matching url

074bf9d

add: a pipe to meet the language changes

a257b74

add: services, utils and tests for the url based localization configu…

337e649

…ration

update: routes to implement related pipe for url based localization

9d0e040

update: breadcrumbs for url based localization

34d5bc1

update: angular documentation for url-based localization

a887fa9

Optimised images with calibre/image-actions

5e3ba18

sumeyyeKurtulus requested a review from fahrigedik April 3, 2026 06:03

maliming modified the milestones: 10.3-preview, 10.4-preview Apr 3, 2026

maliming changed the base branch from rel-10.3 to dev April 3, 2026 08:34

gizemmutukurt removed their request for review April 6, 2026 05:04

EngincanV merged commit 7b7b07e into dev Apr 6, 2026

EngincanV deleted the feature/url-based-localization branch April 6, 2026 05:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Implement route-based culture support in localization.#25174

feat: Implement route-based culture support in localization.#25174
EngincanV merged 29 commits intodevfrom
feature/url-based-localization

maliming commented Mar 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 3, 2026

Uh oh!

sumeyyeKurtulus commented Apr 3, 2026

Uh oh!

gizemmutukurt commented Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

maliming commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes for the Angular team

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

github-actions Bot commented Apr 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 3, 2026

Uh oh!

sumeyyeKurtulus commented Apr 3, 2026

Uh oh!

gizemmutukurt commented Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

maliming commented Mar 30, 2026 •

edited

Loading