diff --git a/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/POST.md b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/POST.md index f791d4edd9..f00ce9a12b 100644 --- a/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/POST.md +++ b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/POST.md @@ -25,12 +25,20 @@ Configure(options => That is the only change you need to make. +## MVC / Razor Pages + +MVC and Razor Pages have the most complete support — everything works automatically. No code changes needed in your pages or controllers. + +![MVC sample — English](images/mvc-home-en.png) + +![MVC sample — Turkish](images/mvc-home-tr.png) + ## What Happens Automatically When you set `UseRouteBasedCulture = true`, ABP automatically: - Registers ASP.NET Core's built-in [`RouteDataRequestCultureProvider`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.localization.routing.routedatarequestcultureprovider) to detect culture from the URL path. -- Adds a `{culture}/{controller}/{action}` conventional route for MVC controllers, with a regex constraint to prevent non-culture URL segments (like `/enterprise/products`) from matching. +- Adds a `{culture}/{controller}/{action}` conventional route for MVC controllers, with a route constraint to prevent non-culture URL segments (like `/enterprise/products`) from matching. - Adds `{culture}/...` route selectors to all Razor Pages at startup. - Injects the current culture into all `Url.Page()` and `Url.Action()` calls, so generated URLs automatically include the culture prefix. - Prepends the culture prefix to navigation menu item URLs. @@ -72,6 +80,14 @@ No theme changes, no language switcher changes — the existing UI component jus Blazor Server and Blazor WebAssembly (WebApp) both support URL-based localization. Culture detection and cookie persistence work automatically on the initial page load (SSR). Menu URLs and language switching also work automatically. +![Blazor Server sample](images/blazor-server-zh-hans.png) + +![Blazor WebApp sample](images/blazor-webapp-tr.png) + +ABP's built-in module pages (Identity, Settings, etc.) also work with URL-based localization out of the box: + +![Identity module — User Management](images/module-identity-users.png) + ### Manual step: Blazor component routes The only manual step for Blazor is adding `@page "/{culture}/..."` routes to your own pages. ASP.NET Core does not support automatically adding route selectors to Blazor components (unlike Razor Pages), so you must add them explicitly: @@ -122,6 +138,18 @@ URL-based localization is fully compatible with ABP's multi-tenant routing. Lang | **Blazor Server** | Manual `@page` routes | N/A | Automatic | Automatic | Add `{culture}` route to pages | | **Blazor WebApp (WASM)** | Manual `@page` routes | N/A | Automatic | Automatic | Add `{culture}` route to pages | +## Running the Sample + +A runnable sample is available at [abp-samples/UrlBasedLocalization](https://github.com/abpframework/abp-samples/tree/master/UrlBasedLocalization), with three projects: + +| Project | UI Type | URL | Command | +|---|---|---|---| +| `BookStore.Mvc` | MVC / Razor Pages | `https://localhost:44335` | `dotnet run --project src/BookStore.Mvc` | +| `BookStore.Blazor.Server` | Blazor Server | `https://localhost:44336` | `dotnet run --project src/BookStore.Blazor.Server` | +| `BookStore.Blazor.WebApp` | Blazor WebApp (InteractiveAuto) | `https://localhost:44337` | `dotnet run --project src/BookStore.Blazor.WebApp` | + +Supported languages: English, Türkçe, Français, 简体中文. + ## Summary To add SEO-friendly localized URL paths to your ABP application: @@ -131,8 +159,6 @@ To add SEO-friendly localized URL paths to your ABP application: Everything else — route registration, URL generation, menu links, and language switching — is handled automatically. -A runnable sample is available at [abp-samples/UrlBasedLocalization](https://github.com/abpframework/abp-samples/tree/master/UrlBasedLocalization). It includes MVC, Blazor Server, and Blazor WebApp projects with English, Turkish, French, and Simplified Chinese. - ## References - [URL-Based Localization — ABP Documentation](https://abp.io/docs/latest/framework/fundamentals/url-based-localization) diff --git a/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/blazor-server-zh-hans.png b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/blazor-server-zh-hans.png new file mode 100644 index 0000000000..a904a7b5bb Binary files /dev/null and b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/blazor-server-zh-hans.png differ diff --git a/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/blazor-webapp-tr.png b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/blazor-webapp-tr.png new file mode 100644 index 0000000000..8a7de7b194 Binary files /dev/null and b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/blazor-webapp-tr.png differ diff --git a/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/module-identity-users.png b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/module-identity-users.png new file mode 100644 index 0000000000..61f7fc531b Binary files /dev/null and b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/module-identity-users.png differ diff --git a/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-en.png b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-en.png new file mode 100644 index 0000000000..fba017397b Binary files /dev/null and b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-en.png differ diff --git a/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-tr.png b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-tr.png new file mode 100644 index 0000000000..f9cdc9bbc5 Binary files /dev/null and b/docs/en/Community-Articles/2026-03-29-Url-Based-Localization/images/mvc-home-tr.png differ diff --git a/docs/en/framework/fundamentals/url-based-localization.md b/docs/en/framework/fundamentals/url-based-localization.md index 1271bdd359..de40d41c32 100644 --- a/docs/en/framework/fundamentals/url-based-localization.md +++ b/docs/en/framework/fundamentals/url-based-localization.md @@ -29,7 +29,7 @@ That's all you need. The framework automatically handles the rest. When you set `UseRouteBasedCulture` to `true`, ABP automatically registers the following: * **`RouteDataRequestCultureProvider`** — A built-in ASP.NET Core provider that reads `{culture}` from route data. ABP inserts it after `QueryStringRequestCultureProvider` and before `CookieRequestCultureProvider`. -* **`{culture:regex(...)}/{controller}/{action}` route** — A conventional route for MVC controllers. The `{culture}` parameter includes a regex constraint matching IETF BCP 47 language tags, so URLs like `/enterprise/products` are not mistaken for culture-prefixed routes. +* **`{culture}/{controller}/{action}` route** — A conventional route for MVC controllers. The `{culture}` parameter uses a custom route constraint (`AbpCultureRouteConstraint`) that only matches culture values configured in `AbpLocalizationOptions.Languages`, so URLs like `/enterprise/products` are not mistaken for culture-prefixed routes. * **`AbpCultureRoutePagesConvention`** — An `IPageRouteModelConvention` that adds `{culture}/...` route selectors to all Razor Pages. * **`AbpCultureRouteUrlHelperFactory`** — Replaces the default `IUrlHelperFactory` to auto-inject culture into `Url.Page()` and `Url.Action()` calls. * **`AbpCultureMenuItemUrlProvider`** — Prepends the culture prefix to navigation menu item URLs (MVC / Blazor Server).