diff --git a/docs/en/Localization.md b/docs/en/Localization.md index 37104a4878..a33dff1779 100644 --- a/docs/en/Localization.md +++ b/docs/en/Localization.md @@ -100,8 +100,6 @@ Configure(options => > The [application startup template](Startup-Templates/Application.md) sets `DefaultResourceType` to the localization resource of the application. -See the *Client Side* section below for a use case. - ### Short Localization Resource Name Localization resources are also available in the client (JavaScript) side. So, setting a short name for the localization resource makes it easy to use localization texts. Example: @@ -156,13 +154,13 @@ services.Configure(options => * If an extension file defines the same localized string, it overrides the string. -## Getting Localized Texts +## Getting the Localized Texts -### Server Side +Getting the localized text is pretty standard. -Getting the localized text on the server side is pretty standard. +### Simplest Usage In A Class -#### Simplest Usage In A Class +Just inject the `IStringLocalizer` service and use it like shown below: ````C# public class MyService @@ -183,9 +181,13 @@ public class MyService ##### Format Arguments -Format arguments can be passed after the localization key. If your message is `Hello {0}, welcome!`, then you can pass the `{0}` argument to the localizer like `_localizer["HelloMessage", "John"]` +Format arguments can be passed after the localization key. If your message is `Hello {0}, welcome!`, then you can pass the `{0}` argument to the localizer like `_localizer["HelloMessage", "John"]`. + +> Refer to the [Microsoft's localization documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization) for details about using the localization. -#### Simplest Usage In A Razor View/Page +### Using In A Razor View/Page + +Use `IHtmlLocalizer` in razor views/pages; ````c# @inject IHtmlLocalizer Localizer @@ -193,54 +195,59 @@ Format arguments can be passed after the localization key. If your message is `H

@Localizer["HelloWorld"]

```` -Refer to the [Microsoft's localization documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization) for details about using localization on the server side. - -### Client Side - -ABP provides JavaScript services to use the same localized texts in the client side. - -#### getResource - -`abp.localization.getResource` function is used to get a localization resource: - -````js -var testResource = abp.localization.getResource('Test'); -```` - -Then you can localize a string based on this resource: +### Special Base Classes -````js -var str = testResource('HelloWorld'); -```` +Some ABP Framework base classes provide a `L` property to use the localizer even easier. -#### localize +**Example: Localize a text in an application service method** -`abp.localization.localize` function is a shortcut where you can both specify the text name and the resource name: +```csharp +using System.Threading.Tasks; +using MyProject.Localization; +using Volo.Abp.Application.Services; -````js -var str = abp.localization.localize('HelloWorld', 'Test'); -```` +namespace MyProject +{ + public class TestAppService : ApplicationService + { + public TestAppService() + { + LocalizationResource = typeof(MyProjectResource); + } -`HelloWorld` is the text to localize, where `Test` is the localization resource name here. + public async Task DoIt() + { + var str = L["HelloWorld"]; + } + } +} +``` -If you don't specify the localization resource name, it uses the default localization resource defined on the `AbpLocalizationOptions` (see the *Default Resource* section above). Example: +When you set the `LocalizationResource` in the constructor, the `ApplicationService` class uses that resource type when you use the `L` property, just like in the `DoIt()` method. -````js -var str = abp.localization.localize('HelloWorld'); //uses the default resource -```` +Setting `LocalizationResource` in every application service can be tedious. You can create an abstract base application service class, set it there and derive your application services from that base class. This is already implemented when you create a new project with the [startup templates](Startup-Templates/Application.md). So, you can simply inherit from the base class directly use the `L` property: -##### Format Arguments +```csharp +using System.Threading.Tasks; -If your localized string contains arguments, like `Hello {0}, welcome!`, you can pass arguments to the localization methods. Examples: +namespace MyProject +{ + public class TestAppService : MyProjectAppService + { + public async Task DoIt() + { + var str = L["HelloWorld"]; + } + } +} +``` -````js -var str1 = abp.localization.getResource('Test')('HelloWelcomeMessage', 'John'); -var str2 = abp.localization.localize('HelloWorld', 'Test', 'John'); -```` +The `L` property is also available for some other base classes like `AbpController` and `AbpPageModel`. -Both of the samples above produce the output `Hello John, welcome!`. +## The Client Side -## See Also +See the following documents to learn how to reuse the same localization texts in the JavaScript side; -* [Localization in Angular UI](UI/Angular/Localization.md) -* [Forms & Validation](UI/AspNetCore/Forms-Validation.md) for the ASP.NET Core MVC / Razor Pages UI \ No newline at end of file +* [Localization for the MVC / Razor Pages UI](UI/AspNetCore/JavaScript-API/Localization.md) +* [Localization for the Blazor UI](UI/Blazor/Localization.md) +* [Localization for the Angular UI](UI/Angular/Localization.md) \ No newline at end of file diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Index.md b/docs/en/UI/AspNetCore/JavaScript-API/Index.md index d37f8c907f..bca62835f7 100644 --- a/docs/en/UI/AspNetCore/JavaScript-API/Index.md +++ b/docs/en/UI/AspNetCore/JavaScript-API/Index.md @@ -10,7 +10,7 @@ ABP provides a set of JavaScript APIs for ASP.NET Core MVC / Razor Pages applica * abp.dom * abp.event * abp.features -* abp.localization +* [abp.localization](Localization.md) * abp.log * [abp.message](Message.md) * abp.ModalManager diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Localization.md b/docs/en/UI/AspNetCore/JavaScript-API/Localization.md new file mode 100644 index 0000000000..41e5d02c49 --- /dev/null +++ b/docs/en/UI/AspNetCore/JavaScript-API/Localization.md @@ -0,0 +1,46 @@ +# ASP.NET Core MVC / Razor Pages UI: JavaScript Localization API + +Localization API allows you to reuse the server side localization resources in the client side. + +> This document only explains the JavaScript API. See the [localization document](../../../Localization.md) to understand the ABP localization system. + +## Basic Usage + +`abp.localization.getResource(...)` function is used to get a localization resource: + +````js +var testResource = abp.localization.getResource('Test'); +```` + +Then you can localize a string based on this resource: + +````js +var str = testResource('HelloWorld'); +```` + +`abp.localization.localize(...)` function is a shortcut where you can both specify the text name and the resource name: + +````js +var str = abp.localization.localize('HelloWorld', 'Test'); +```` + +`HelloWorld` is the text to localize, where `Test` is the localization resource name here. + +### Default Localization Resource + +If you don't specify the localization resource name, it uses the **default localization resource** defined on the `AbpLocalizationOptions` (see the *Default Resource* section above). Example: + +````js +var str = abp.localization.localize('HelloWorld'); //uses the default resource +```` + +### Format Arguments + +If your localized string contains arguments, like `Hello {0}, welcome!`, you can pass arguments to the localization methods. Examples: + +````js +var str1 = abp.localization.getResource('Test')('HelloWelcomeMessage', 'John'); +var str2 = abp.localization.localize('HelloWelcomeMessage', 'Test', 'John'); +```` + +Assuming the `HelloWelcomeMessage` is localized as `Hello {0}, welcome!`, both of the samples above produce the output `Hello John, welcome!`. \ No newline at end of file diff --git a/docs/en/UI/Blazor/Localization.md b/docs/en/UI/Blazor/Localization.md new file mode 100644 index 0000000000..e6cf761ce3 --- /dev/null +++ b/docs/en/UI/Blazor/Localization.md @@ -0,0 +1,3 @@ +# Blazor UI: Localization + +Blazor applications can reuse the same `IStringLocalizer` service that is explained in the [localization document](../../Localization.md). All the localization resources and texts available in the server side are usable in the Blazor application. \ No newline at end of file