From 687768d2202ffb5cc3ac3ba279d3203726cf9e7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= Date: Sun, 29 Apr 2018 15:06:21 +0300 Subject: [PATCH] Creating the localization document --- docs/Index.md | 2 +- docs/Localization.md | 150 ++++++++++++++++++ docs/Virtual-File-System.md | 2 +- .../AbpValidation/AbpValidationResource.cs | 2 + 4 files changed, 154 insertions(+), 2 deletions(-) create mode 100644 docs/Localization.md diff --git a/docs/Index.md b/docs/Index.md index 0fd752b9af..64ed45a053 100644 --- a/docs/Index.md +++ b/docs/Index.md @@ -8,7 +8,7 @@ * Fundamentals * Dependency Injection * [Virtual File System](Virtual-File-System.md) - * Localization + * [Localization](Localization.md) * Exception Handling * [Multi Tenancy](Multi-Tenancy.md) * Module Development diff --git a/docs/Localization.md b/docs/Localization.md new file mode 100644 index 0000000000..0febed7bfa --- /dev/null +++ b/docs/Localization.md @@ -0,0 +1,150 @@ +## Localization + +ABP's localization system is built on top of the `Microsoft.Extensions.Localization` package and compatible with the [Microsoft's localization documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization). + +### Volo.Abp.Localization Package + +Volo.Abp.Localization is the core package of the localization system. Install it to your project using the package manager console (PMC): + +``` +Install-Package Volo.Abp.Localization +``` + +> This package is already installed by default with the startup template. So, most of the time, you don't need to install it manually. + +Then you can add **AbpLocalizationModule** dependency to your module: + +```c# +using Volo.Abp.Modularity; +using Volo.Abp.Localization; + +namespace MyCompany.MyProject +{ + [DependsOn(typeof(AbpLocalizationModule))] + public class MyModule : AbpModule + { + //... + } +} +``` + +#### Creating A Localization Resource + +A localization resource is used to group related localization strings together and separate them from other localization strings of the application. A module generally defines its own localization resource. Localization resource is just a plain class. Example: + +````C# +public class TestResource +{ +} +```` + +Then it should be added using `AbpLocalizationOptions` as shown below: + +````C# +[DependsOn(typeof(AbpLocalizationModule))] +public class MyModule : AbpModule +{ + public override void ConfigureServices(IServiceCollection services) + { + services.Configure(options => + { + options.FileSets.AddEmbedded(); + }); + + services.Configure(options => + { + options.Resources.AddVirtualJson( + "en", + "/Localization/Resources/Test" + ); + }); + } +} +```` + +In this example; + +* Used JSON files to store the localization strings. +* JSON files are embedded into the assembly using the [virtual file system](Virtual-File-System.md). + +JSON files are located under "/Localization/Resources/Test" project folder as shown below: + +![localization-resource-json-files](images/localization-resource-json-files.png) + +A JSON localization file content is shown below: + +````json +{ + "culture": "en", + "texts": { + "HelloWorld": "Hello World!" + } +} +```` + +* Every localization file should define the `culture` code for the file (like "en" or "en-US"). +* `texts` section just contains key-value collection of the localization strings (keys may have spaces too). + +##### 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: + +````C# +[ShortLocalizationResourceName("Test")] +public class TestResource +{ +} +```` + +See the Getting Localized Test / Client Side section below. + +##### Inherit From Other Resources + +A resource can inherit from other resources which makes possible to re-use existing localization strings without referring the existing resource. Example: + +````C# +[InheritResource(typeof(AbpValidationResource))] +public class TestResource +{ +} +```` + +Alternative inheritance by configuring the `AbpLocalizationOptions`: + +````C# +services.Configure(options => +{ + options.Resources.AddVirtualJson("en", "/Localization/Resources/Test"); + + //Inherit from an existing resource + options.Resources.AddBaseTypes(typeof(AbpValidationResource)); +}); +```` + +* A resource may inherit from multiple resources. +* If the new resource defines the same localized string, it overrides the string. + +##### Extending Existing Resource + +Inheriting from a resource creates a new resource without modifying the existing one. In some cases, you may want to not create a new resource but directly extend an existing resource. Example: + +````C# +services.Configure(options => +{ + options.Resources.ExtendWithVirtualJson( + "/Localization/Resources/Test/Extensions" + ); +}); +```` + +If an extension file defines the same localized string, it overrides the string. + +#### Getting Localized Texts + +##### Server Side + +Getting the localized text on the server side is pretty standard. So, you can refer to the [Microsoft's localization documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization). + +##### Client Side + +TODO... \ No newline at end of file diff --git a/docs/Virtual-File-System.md b/docs/Virtual-File-System.md index 45d31d2eb7..e15c84aab3 100644 --- a/docs/Virtual-File-System.md +++ b/docs/Virtual-File-System.md @@ -4,7 +4,7 @@ Virtual File System makes possible to manage files those are not physically exis ### Volo.Abp.VirtualFileSystem Package -Volo.Abp.VirtualFileSystem it the core package of the virtual file system. Install it to your project using the package manager console (PMC): +Volo.Abp.VirtualFileSystem is the core package of the virtual file system. Install it to your project using the package manager console (PMC): ``` Install-Package Volo.Abp.VirtualFileSystem diff --git a/src/Volo.Abp.Localization/Volo/Abp/Localization/Resources/AbpValidation/AbpValidationResource.cs b/src/Volo.Abp.Localization/Volo/Abp/Localization/Resources/AbpValidation/AbpValidationResource.cs index 02a6331c0a..0fe4f6d7d3 100644 --- a/src/Volo.Abp.Localization/Volo/Abp/Localization/Resources/AbpValidation/AbpValidationResource.cs +++ b/src/Volo.Abp.Localization/Volo/Abp/Localization/Resources/AbpValidation/AbpValidationResource.cs @@ -1,5 +1,7 @@ namespace Volo.Abp.Localization.Resources.AbpValidation { + //TODO: Move to Volo.Abp.Validation! + [ShortLocalizationResourceName("AbpValidation")] public class AbpValidationResource {