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 6b244db1ff..bca62835f7 100644 --- a/docs/en/UI/AspNetCore/JavaScript-API/Index.md +++ b/docs/en/UI/AspNetCore/JavaScript-API/Index.md @@ -10,11 +10,11 @@ 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 -* abp.notify +* [abp.notify](Notify.md) * abp.security * abp.setting * abp.ui 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..0897b99268 --- /dev/null +++ b/docs/en/UI/AspNetCore/JavaScript-API/Localization.md @@ -0,0 +1,143 @@ +# 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. + +### Fallback Logic + +If given texts was not localized, localization method returns the given key as the localization result. + +### Default Localization Resource + +If you don't specify the localization resource name, it uses the **default localization resource** defined on the `AbpLocalizationOptions` (see the [localization document](../../../Localization.md)). + +**Example: Using the default localization resource** + +````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 testSource = abp.localization.getResource('Test'); +var str1 = testSource('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!`. + +## Other Properties & Methods + +### abp.localization.values + +`abp.localization.values` property stores all the localization resources, keys and their values. + +### abp.localization.isLocalized + +Returns a boolean indicating that if the given text was localized or not. + +**Example** + +````js +abp.localization.isLocalized('ProductName', 'MyResource'); +```` + +Returns `true` if the `ProductName` text was localized for the `MyResource` resource. Otherwise, returns `false`. You can leave the resource name empty to use the default localization resource. + +### abp.localization.defaultResourceName + +`abp.localization.defaultResourceName` can be set to change the default localization resource. You normally don't set this since the ABP Framework automatically sets is based on the server side configuration. + +### abp.localization.currentCulture + +`abp.localization.currentCulture` returns an object to get information about the **currently selected language**. + +An example value of this object is shown below: + +````js +{ + "displayName": "English", + "englishName": "English", + "threeLetterIsoLanguageName": "eng", + "twoLetterIsoLanguageName": "en", + "isRightToLeft": false, + "cultureName": "en", + "name": "en", + "nativeName": "English", + "dateTimeFormat": { + "calendarAlgorithmType": "SolarCalendar", + "dateTimeFormatLong": "dddd, MMMM d, yyyy", + "shortDatePattern": "M/d/yyyy", + "fullDateTimePattern": "dddd, MMMM d, yyyy h:mm:ss tt", + "dateSeparator": "/", + "shortTimePattern": "h:mm tt", + "longTimePattern": "h:mm:ss tt" + } +} +```` + +### abp.localization.languages + +Used to get list of all **available languages** in the application. An example value of this object is shown below: + +````js +[ + { + "cultureName": "en", + "uiCultureName": "en", + "displayName": "English", + "flagIcon": null + }, + { + "cultureName": "fr", + "uiCultureName": "fr", + "displayName": "Français", + "flagIcon": null + }, + { + "cultureName": "pt-BR", + "uiCultureName": "pt-BR", + "displayName": "Português", + "flagIcon": null + }, + { + "cultureName": "tr", + "uiCultureName": "tr", + "displayName": "Türkçe", + "flagIcon": null + }, + { + "cultureName": "zh-Hans", + "uiCultureName": "zh-Hans", + "displayName": "简体中文", + "flagIcon": null + } +] +```` + diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Notify.md b/docs/en/UI/AspNetCore/JavaScript-API/Notify.md new file mode 100644 index 0000000000..ba2b0d3de5 --- /dev/null +++ b/docs/en/UI/AspNetCore/JavaScript-API/Notify.md @@ -0,0 +1,45 @@ +# ASP.NET Core MVC / Razor Pages UI: JavaScript Notify API + +Notify API is used to show toast style, auto disappearing UI notifications to the end user. It is implemented by the [Toastr](https://github.com/CodeSeven/toastr) library by default. + +## Quick Example + +Use `abp.notify.success(...)` function to show a success message: + +````js +abp.notify.success( + 'The product "Acme Atom Re-Arranger" has been successfully deleted.', + 'Deleted the Product' +); +```` + +A notification message is shown at the bottom right of the page: + +![js-message-success](D:/Github/abp/docs/en/images/js-notify-success.png) + +## Notification Types + +There are four types of pre-defined notifications; + +* `abp.notify.success(...)` +* `abp.notify.info(...)` +* `abp.notify.warn(...)` +* `abp.notify.error(...)` + +All of the methods above gets the following parameters; + +* `message`: A message (`string`) to show to the user. +* `title`: An optional title (`string`). +* `options`: Additional options to be passed to the underlying library, to the Toastr by default. + +## Toastr Configuration + +The notification API is implemented by the [Toastr](https://github.com/CodeSeven/toastr) library by default. You can see its own configuration options. + +**Example: Show toast messages on the top right of the page** + +````js +toastr.options.positionClass = 'toast-top-right'; +```` + +> ABP sets this option to `toast-bottom-right` by default. You can override it just as shown above. \ 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 diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index c274db0085..5ae74c6608 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -451,6 +451,10 @@ "text": "Overall", "path": "UI/AspNetCore/JavaScript-API/Index.md" }, + { + "text": "Localization", + "path": "UI/AspNetCore/JavaScript-API/Localization.md" + }, { "text": "AJAX", "path": "UI/AspNetCore/JavaScript-API/Ajax.md" diff --git a/docs/en/images/js-notify-success.png b/docs/en/images/js-notify-success.png new file mode 100644 index 0000000000..04489bc7ce Binary files /dev/null and b/docs/en/images/js-notify-success.png differ