Add multi-lingual-entities document

5 years ago · e9ae597adb
4 changed files with 208 additions and 0 deletions
--- a/docs/en/Multi-Lingual-Entities.md
+++ b/docs/en/Multi-Lingual-Entities.md
@ -0,0 +1,100 @@
+# Multi Lingual Entities
+
+ABP Framework defines two basic interfaces for Multi-Lingual entity definitions to provide a standard model for translating entities.
+
+## IHasMultiLingual
+
+`IHasMultiLingual<TTranslation>` interface is used to mark multi lingual entities. The entities marked with `IHasMultiLingual<TTranslation>` interface must define language-neutral information. The entities marked with `IHasMultiLingual<TTranslation>` contains a collection of Translations which contains language-dependent information.
+
+Example:
+
+```csharp
+public class Product : Entity, IMultiLingualEntity<ProductTranslation>
+{
+    public decimal Price { get; set; }
+
+    public ICollection<ProductTranslation> Translations { get; set; }
+}
+```
+
+## IMultiLingualTranslation
+
+`IMultiLingualTranslation` interface is used to mark translation of a Multi-Lingual entity. The entities marked with `IMultiLingualTranslation` interface must define language dependent information. The entities marked with `IMultiLingualTranslation` contains Language field which contains a language code for the translation.
+
+Example:
+
+```csharp
+public class ProductTranslation : Entity, IMultiLingualTranslation
+{
+    public string Name { get; set; }
+
+    public string Language { get; set; }
+}
+```
+
+## Map to DTO object
+
+ABP provdies the [Object To Object Mapping](Object-To-Object-Mapping.md) system, you can implement the `IObjectMapper<TSource, TDestination>` interface to map multi lingual entities to DTOs.
+
+Example:
+
+```csharp
+public class MultiLingualProductObjectMapper : IObjectMapper<Product, ProductDto>, ITransientDependency
+{
+    private readonly IMultiLingualObjectManager _multiLingualObjectManager;
+
+    public MultiLingualProductObjectMapper(IMultiLingualObjectManager multiLingualObjectManager)
+    {
+        _multiLingualObjectManager = multiLingualObjectManager;
+    }
+
+    public ProductDto Map(Product source)
+    {
+        var translation = _multiLingualObjectManager.GetTranslation<Product, ProductDto>(source);
+
+        return new ProductDto
+        {
+            Price = source.Price,
+            Id = source.Id,
+            Name = translation?.Name
+        };
+    }
+
+    public ProductDto Map(Product source, ProductDto destination)
+    {
+        return default;
+    }
+}
+
+```
+
+### AutoMapper integration
+
+ABP provides the `CreateMultiLingualMap` extension method for mapping multilingual entities to DTOs.
+
+Example:
+
+```csharp
+public class ProductProfile : Profile
+{
+    public ProductProfile()
+    {
+        var mapResult = this.CreateMultiLingualMap<Product, ProductTranslation, ProductDto>();
+    }
+}
+```
+
+`CreateMultiLingualMap` extension method returns an object of type `CreateMultiLingualMapResult` which contains `EntityMap` and `TranslationMap` fields. These fields can be used to customize multi lingual mapping.
+
+Example:
+
+```csharp
+this.CreateMultiLingualMap<Order, OrderTranslation, OrderListDto>(context)
+    .EntityMap.ForMember(dest => dest.ProductCount, opt => opt.MapFrom(src => src.Products.Count));
+```
+
+## IMultiLingualObjectManager
+
+`IMultiLingualObjectManager` interface defines `GetTranslation` and `GetTranslationAsync` method to get the translation object of the entity.
+
+The default implementation of the `IMultiLingualObjectManager` interface finds the translation with selected UI language first. If there is no translation with selected UI language, then extension method searches for the default language setting (see [Setting](Settings.md)) and uses the translation in default language. If extension method couldn't find any translation in current UI language or default language, it uses one of the existing translations.
--- a/docs/en/docs-nav.json
+++ b/docs/en/docs-nav.json
@ -376,6 +376,10 @@
                  "text": "Entities & Aggregate Roots",
                  "path": "Entities.md"
                },
+                {
+                  "text": "Multi-Lingual-Entities",
+                  "path": "Multi-Lingual-Entities.md"
+                },
                {
                  "text": "Value Objects",
                  "path": "Value-Objects.md"
--- a/docs/zh-Hans/Multi-Lingual-Entities.md
+++ b/docs/zh-Hans/Multi-Lingual-Entities.md
@ -0,0 +1,100 @@
+# 多语言实体
+
+ABP框架为多语言实体定义了两个基本接口用于翻译实体的标准模型.
+
+## IHasMultiLingual
+
+`IHasMultiLingual<TTranslation>` 接口用于标记多语言实体. 通过 `IHasMultiLingual<TTranslation>` 接口被标记为多语言的实体定义与语言无关的信息. 多语言实体包含翻译集合,其中包含与语言有关的信息.
+
+示例:
+
+```csharp
+public class Product : Entity<Guid>, IMultiLingualEntity<ProductTranslation>
+{
+    public decimal Price { get; set; }
+
+    public ICollection<ProductTranslation> Translations { get; set; }
+}
+```
+
+## IMultiLingualTranslation
+
+`IMultiLingualTranslation` 接口用于标记多语言实体的翻译. 通过 `IHasMultiLingual<TTranslation>` 接口被标记为的翻译实体定义与语言有关的信息. 翻译实体包含 `Language` 字段,用于翻译的语言代码.
+
+示例:
+
+```csharp
+public class ProductTranslation : Entity<Guid>, IMultiLingualTranslation
+{
+    public string Name { get; set; }
+
+    public string Language { get; set; }
+}
+```
+
+## 映射为DTO对象
+
+ABP提供了[对象到对象的映射](Object-To-Object-Mapping.md)系统,你可以通过实现 `IObjectMapper<TSource, TDestination>` 接口将多语言实体映射为DTO.
+
+示例:
+
+```csharp
+public class MultiLingualProductObjectMapper : IObjectMapper<Product, ProductDto>, ITransientDependency
+{
+    private readonly IMultiLingualObjectManager _multiLingualObjectManager;
+
+    public MultiLingualProductObjectMapper(IMultiLingualObjectManager multiLingualObjectManager)
+    {
+        _multiLingualObjectManager = multiLingualObjectManager;
+    }
+
+    public ProductDto Map(Product source)
+    {
+        var translation = _multiLingualObjectManager.GetTranslation<Product, ProductDto>(source);
+
+        return new ProductDto
+        {
+            Price = source.Price,
+            Id = source.Id,
+            Name = translation?.Name
+        };
+    }
+
+    public ProductDto Map(Product source, ProductDto destination)
+    {
+        return default;
+    }
+}
+
+```
+
+### AutoMapper集成
+
+ABP提供了 `CreateMultiLingualMap` 扩展方法用于将多语言实体映射为DTO.
+
+示例:
+
+```csharp
+public class ProductProfile : Profile
+{
+    public ProductProfile()
+    {
+        var mapResult = this.CreateMultiLingualMap<Product, ProductTranslation, ProductDto>();
+    }
+}
+```
+
+`CreateMultiLingualMap` 扩展方法返回了一个类型为 `CreateMultiLingualMapResult` 的对象,它包含 `EntityMap` 和 `TranslationMap` 字段. 这些字段可以用于自定义多语言映射.
+
+示例:
+
+```csharp
+this.CreateMultiLingualMap<Order, OrderTranslation, OrderListDto>(context)
+    .EntityMap.ForMember(dest => dest.ProductCount, opt => opt.MapFrom(src => src.Products.Count));
+```
+
+## IMultiLingualObjectManager
+
+`IMultiLingualObjectManager` 接口定义了 `GetTranslation` 和 `GetTranslationAsync` 方法用于获取实体当前的翻译对象.
+
+`IMultiLingualObjectManager` 的默认实现首先使用当前的UI语言寻找翻译, 如果当前的UI语言没有对应的翻译, 那么会搜索默认语言设置(参阅[设置](Settings.md))用于寻找翻译. 如果默认语言没有对应的翻译, 那么它会返回已存在翻译集合中的第一个翻译对象.
--- a/docs/zh-Hans/docs-nav.json
+++ b/docs/zh-Hans/docs-nav.json
@ -354,6 +354,10 @@
                  "text": "实体&聚合根",
                  "path": "Entities.md"
                },
+                {
+                  "text": "多语言实体",
+                  "path": "Multi-Lingual-Entities.md"
+                },
                {
                  "text": "值对象"
                },