diff --git a/docs/en/Multi-Lingual-Entities.md b/docs/en/Multi-Lingual-Entities.md new file mode 100644 index 0000000000..85746a3fea --- /dev/null +++ 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` interface is used to mark multi lingual entities. The entities marked with `IHasMultiLingual` interface must define language-neutral information. The entities marked with `IHasMultiLingual` contains a collection of Translations which contains language-dependent information. + +Example: + +```csharp +public class Product : Entity, IMultiLingualEntity +{ + public decimal Price { get; set; } + + public ICollection 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` interface to map multi lingual entities to DTOs. + +Example: + +```csharp +public class MultiLingualProductObjectMapper : IObjectMapper, ITransientDependency +{ + private readonly IMultiLingualObjectManager _multiLingualObjectManager; + + public MultiLingualProductObjectMapper(IMultiLingualObjectManager multiLingualObjectManager) + { + _multiLingualObjectManager = multiLingualObjectManager; + } + + public ProductDto Map(Product source) + { + var translation = _multiLingualObjectManager.GetTranslation(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(); + } +} +``` + +`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(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. \ No newline at end of file diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index efca73a484..ec3341c623 100644 --- 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" diff --git a/docs/zh-Hans/Multi-Lingual-Entities.md b/docs/zh-Hans/Multi-Lingual-Entities.md new file mode 100644 index 0000000000..2deff4e38f --- /dev/null +++ b/docs/zh-Hans/Multi-Lingual-Entities.md @@ -0,0 +1,100 @@ +# 多语言实体 + +ABP框架为多语言实体定义了两个基本接口用于翻译实体的标准模型. + +## IHasMultiLingual + +`IHasMultiLingual` 接口用于标记多语言实体. 通过 `IHasMultiLingual` 接口被标记为多语言的实体定义与语言无关的信息. 多语言实体包含翻译集合,其中包含与语言有关的信息. + +示例: + +```csharp +public class Product : Entity, IMultiLingualEntity +{ + public decimal Price { get; set; } + + public ICollection Translations { get; set; } +} +``` + +## IMultiLingualTranslation + +`IMultiLingualTranslation` 接口用于标记多语言实体的翻译. 通过 `IHasMultiLingual` 接口被标记为的翻译实体定义与语言有关的信息. 翻译实体包含 `Language` 字段,用于翻译的语言代码. + +示例: + +```csharp +public class ProductTranslation : Entity, IMultiLingualTranslation +{ + public string Name { get; set; } + + public string Language { get; set; } +} +``` + +## 映射为DTO对象 + +ABP提供了[对象到对象的映射](Object-To-Object-Mapping.md)系统,你可以通过实现 `IObjectMapper` 接口将多语言实体映射为DTO. + +示例: + +```csharp +public class MultiLingualProductObjectMapper : IObjectMapper, ITransientDependency +{ + private readonly IMultiLingualObjectManager _multiLingualObjectManager; + + public MultiLingualProductObjectMapper(IMultiLingualObjectManager multiLingualObjectManager) + { + _multiLingualObjectManager = multiLingualObjectManager; + } + + public ProductDto Map(Product source) + { + var translation = _multiLingualObjectManager.GetTranslation(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(); + } +} +``` + +`CreateMultiLingualMap` 扩展方法返回了一个类型为 `CreateMultiLingualMapResult` 的对象,它包含 `EntityMap` 和 `TranslationMap` 字段. 这些字段可以用于自定义多语言映射. + +示例: + +```csharp +this.CreateMultiLingualMap(context) + .EntityMap.ForMember(dest => dest.ProductCount, opt => opt.MapFrom(src => src.Products.Count)); +``` + +## IMultiLingualObjectManager + +`IMultiLingualObjectManager` 接口定义了 `GetTranslation` 和 `GetTranslationAsync` 方法用于获取实体当前的翻译对象. + +`IMultiLingualObjectManager` 的默认实现首先使用当前的UI语言寻找翻译, 如果当前的UI语言没有对应的翻译, 那么会搜索默认语言设置(参阅[设置](Settings.md))用于寻找翻译. 如果默认语言没有对应的翻译, 那么它会返回已存在翻译集合中的第一个翻译对象. diff --git a/docs/zh-Hans/docs-nav.json b/docs/zh-Hans/docs-nav.json index 4f47dd2760..241633caf5 100644 --- 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": "值对象" },