Skip to content

Commit 941766e

Browse files
aksoftware98aksoftware98
authored
Merge pull request #71 from aksoftware98/update-docs
Update docs
2 parents 547e4e5 + 46a2429 commit 941766e

1 file changed

Lines changed: 89 additions & 81 deletions

File tree

‎README.md‎

Lines changed: 89 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,27 @@
11

2+
23

34

45

56
# AKSoftware.Localization.MultiLanguages
6-
### Version 5.9 is here [Check out What's New](#whats-new-in-version-590)
7+
### v6.0.0-alpha
78
[![Build Badge](https://aksoftware98.visualstudio.com/AkMultiLanguages/_apis/build/status/aksoftware98.multilanguages?branchName=master)](https://aksoftware98.visualstudio.com/AkMultiLanguages/_build/latest?definitionId=4&branchName=master)
89

910

1011

1112
![Nuget](https://img.shields.io/nuget/dt/AKSoftware.Localization.MultiLanguages?color=nuget&label=Nuget&style=plastic)
1213

13-
14+
<img width="100" src="https://github.com/aksoftware98/multilanguages/blob/master/src/AKSoftware.Localization.MultiLanguages/AkMultiLanguages.png?raw=true" />
15+
<img width="100" src="https://github.com/aksoftware98/multilanguages/blob/master/src/AKSoftware.Localization.MultiLanguages.Blazor/AkMultiLanguages.png?raw=true" />
16+
17+
.NET most advanced localization package for your solutions, light, fast, super easy to use, and much more.
18+
Making your app available in many languages should be a simple straightforward process, *AKSoftware.Localization.Multilanguages* offers the ultimate solution.
19+
20+
<img width="400" src="https://github.com/aksoftware98/multilanguages/blob/master/Images/v6/yaml-based.png?raw=true" />
21+
<img width="400" src="https://github.com/aksoftware98/multilanguages/blob/master/Images/v6/hierarchy-friendly.png?raw=true" />
22+
<img width="400" src="https://github.com/aksoftware98/multilanguages/blob/master/Images/v6/source-generator.png?raw=true" />
23+
<img width="400" src="https://github.com/aksoftware98/multilanguages/blob/master/Images/v6/interpolation-support.png?raw=true" />
1424

15-
Build awesome .NET applications that supports more than 69+ languages with just a few lines of code, in addition to an easy translation tool that helps you translate all your content to any language you want with just one click
1625

1726
Could be used for all type of .NET Apps (Blazor, UWP, Xamarin, Windows, ASP.NET Core MVC, Razor Pages ....)
1827

@@ -37,103 +46,92 @@ https://youtu.be/Xz68c8GBYz4
3746
![Blazor UI with Japanease](https://raw.githubusercontent.com/aksoftware98/multilanguages/master/Example/BlazorWasmMultiLanguages/BlazorWasmMultiLanguages/wwwroot/Japan.png)
3847

3948

40-
# What's new in Version 5.9.0
41-
Version 5.9.0 with two big achievements:
42-
1. The performance of the library has been improved by 5x especially while retrieving nested keys, due to eliminate the usage of JSON in some places and depend efficiently on the YAML library.
43-
2. The ability to store the Resources in an external folder with a specified path that you can define
44-
To use this feature without using Dependency Injection
45-
You can refer to this sample file here:
46-
[Program.cs sample to fetch keys from folder](https://github.com/aksoftware98/multilanguages/blob/master/src/ConsoleAppSample/Program.cs)
49+
# Why YAML
50+
Most common solution for multilanguage in .NET is the .resx resource files. .resx files are XML based so they are not too friendly to deal with and most likely a GUI tool is needed for keys management. XML is also huge and slower to parse. On the other hand, YAML is new, very fast to parse, and file structure is very simple and doesn't contain any single not-needed character which make the file size too small comparing to the XML one.
51+
For modern SPA apps with Blazor WebAssembly for example, large language files with .resx might slow down the load time for the download.
52+
YAML file structure allows for nested objects which a lovely feature you can take advantage of to build an organized language key-values files without long concatenated names.
53+
Finally, due to the simplicity of YAML, it's makes it very easy to build automation on top of it like source generator and static classes creation.
4754

48-
If you are using dependency injection you can use the newly used method:
49-
``` C#
50-
// For .NET projects consider the following method
51-
services.AddLanguageContainerFromFolder("Resouces", CultureInfo.GetCultureInfo("en-US"));
52-
53-
// For Blazor Server
54-
services.AddLanguageContainerFromFolderForBlazorServer("Resouces", CultureInfo.GetCultureInfo("en-US"));
55-
```
55+
# Features
56+
AKSoftware.Localization.Multilanguage prvoides all the feature set needed for any multilanguage support like:
57+
- Easy to get started.
58+
- Online traslator tool to translate your files in one click for more 65 languages https://akmultilanguages.azurewebsites.net
59+
- Light and high-performant
60+
- Blazor Server & WebAssembly support
61+
- Out of the box state management for **Blazor** components
62+
- Multiple language file sources (Files in folder or embedded files)
63+
- String interpolation support
64+
- Dynamically list all language keys
65+
- Dynamically list all available langauges
66+
- Dependency injection support
67+
- Hierarcy language keys in YAML
68+
- Code generators to generate full keys accessor service, static class with const strings, enums, and more..
69+
- v6.1 will bring the localization assistant to localize existing apps with minimal effort.
70+
- Full UWP support
5671

57-
**Keep in mind, the folder of the resources has to be shipped with your project**
5872

59-
# What's new in Version 5.8.0
60-
Finally **Blazor Server** is here you can get started now.
61-
The **only** change that you need to do that is different from others is in your **program.cs** file make sure to use the following function to register the Language Container
62-
``` C#
63-
...
64-
// Register the language container for Blazor Server
65-
builder.Services.AddLanguageContainerForBlazorServer<EmbeddedResourceKeysProvider>(Assembly.GetExecutingAssembly(), "Resources");
66-
...
67-
```
68-
Check out the following [Blazor Server Sample](https://github.com/aksoftware98/multilanguages/tree/master/src/BlazorServerLocalizationSample)
6973

70-
# UWP Support in Version 5.0.0
74+
# Getting Started
7175

72-
Special thanks for the contributor [Michael Gerfen](https://github.com/gerfen) for updating the library to add support to the UWP.
76+
7377

74-
This version contains a major update that adds support for a new package under the name AKSoftware.Localization.MultiLangauges.UWP you can install it from Nuget with the following command
78+
For Nuget Package Manager install the package
7579

76-
80+
(Nuget Package Manager Console)
7781

7882
``` PS
7983
80-
Install-Package AKSoftware.Localization.MultiLangauges.UWP
84+
Install-Package AKSoftware.Localization.MultiLanguages -Version 6.0.0-alpha
8185
8286
```
8387

84-
85-
86-
# What's new in Version 5.0.0
87-
88-
In the latest version of the library because right it started to support UWP and not only Blazor a new interface and abstract type has been introduced that allows you to easily create a keys provider to fetch your keys not only from the embedded resources, also from any source you would like (External folder, FTP, Azure Blob Storage ...etc)
89-
90-
By default there is the ***EmbeddedResourceKeysProvider*** to fetch the files from the resources and you can create your own by inhereting from the interface ***IKeysProvider***
91-
92-
More about the implementation in the Wiki soon
88+
(Using dotNet CLI)
9389

94-
90+
``` CLI
9591
96-
# Getting Started
92+
dotnet add package AKSoftware.Localization.MultiLanuages --version 6.0.0-alpha
9793
98-
94+
```
9995

100-
For Nuget Package Manager install the package
96+
**For Blazor** additional package is required that helps managing the state of the component when changing the language
10197

10298
(Nuget Package Manager Console)
10399

104100
``` PS
105101
106-
Install-Package AKSoftware.Localization.MultiLanguages
102+
Install-Package AKSoftware.Localization.MultiLanguages.Blazor -Version 6.0.0-alpha
107103
108104
```
109105

110106
(Using dotNet CLI)
111107

112108
``` CLI
113109
114-
dotnet add package AKSoftware.Localization.MultiLanuages
110+
dotnet add package AKSoftware.Localization.MultiLanuages.Blazor --version 6.0.0-alpha
115111
116112
```
117113

118-
**For Blazor** additional package is required that helps managing the state of the component when changing the language
119-
114+
**For Source Generator** install:
120115
(Nuget Package Manager Console)
121-
116+
122117
``` PS
123118
124-
Install-Package AKSoftware.Localization.MultiLanguages.Blazor
119+
Install-Package AKSoftware.Localization.MultiLanguages.SourceGenerator -Version 6.0.0-alpha
125120
126121
```
127122

128123
(Using dotNet CLI)
129124

130125
``` CLI
131126
132-
dotnet add package AKSoftware.Localization.MultiLanuages.Blazor
127+
dotnet add package AKSoftware.Localization.MultiLanuages.SourceGenerator--version 6.0.0-alpha
133128
134129
```
135130

136-
131+
>**Source Generator Note**
132+
> When using the source generator, the package will take care of setting the file as embedded resources, and it generates a new interface named **IKeysAccessor** this service wraps the access to all the keys and tested keys in your language files.
133+
>
134+
> However, the package must be installed the project that contains the en-US.yml file, so if your solution is a single project you can directly install it in the same project. If your solution consists of multiple projects and you want to use the localization across all of them, make sure to create a seperate project for localization and reference it in your other projects.
137135
138136

139137
## Create the Resources Folder
@@ -166,6 +164,9 @@ Welcome: Welcome
166164

167165
Select the file in the Solution Explorer window and from the properties window set the build action property to "Embeded Resources"
168166

167+
>**Note**
168+
>In case of using the Source Generator package, that will be taken care of automatically.
169+
169170

170171

171172
## Translate the file
@@ -232,6 +233,12 @@ builder.Services.AddLanguageContainer<EmbeddedResourceKeysProvider>(Assembly.Get
232233

233234
If you don't specify a default culture the library will try to find the file that matches the culture of the current user, if it's not existing it will try to find any file that matches the same language, then if it's not there it will try to find the English file then the first file in the folder, otherwise it will throw an exception
234235

236+
> **Source Generator Note**
237+
> In case of using the Source Generator and want to have direct access without using the ILanguageContainerService and provide the key as string make sure to also register the auto-generated interface instance in your dependency injection container:
238+
> ``
239+
> builder.Services.AddKeysAccessor();
240+
> ``
241+
235242

236243

237244

@@ -249,25 +256,32 @@ using AKSoftware.Localization.MultiLanguages.Blazor
249256

250257
With in your components that you want to localize inject the service
251258

252-
``` C#
259+
```csharp
253260

254261
@inject ILanguageContainerService languageContainer
255262

263+
```
264+
or with Source Genertaor inject the keys accessor instead
265+
```csharp
266+
@inject IKeysAccessor KeysAccessor
256267
```
257268

258269
And start getting the values from your files just like this
259270

260-
``` Razor
261-
271+
```razor
272+
@* Without Source Generator *@
262273
<h1>@languageContainer.Keys["HelloWorld"]</h1>
263274

275+
@* With Source Generator *@
276+
<h1>@KeysAccessor.HelloWorld</h1>
277+
264278
```
265279

266280

267281

268282
And to be able to get the state updated for each component that contains localized text call the extension method in the OnInitialized or OnInitializedAsync overriden methods for each component as following
269283

270-
``` C#
284+
```csharp
271285

272286
protected override void OnInitialized()
273287

@@ -343,8 +357,8 @@ In C# to replace the value of username and version parameters at runtime you can
343357
344358
345359
346-
```C#
347-
360+
```csharp
361+
// Without Source Generator
348362
_language["Welcome", new
349363

350364
{
@@ -355,6 +369,9 @@ Version = "v4.0"
355369

356370
}]
357371

372+
373+
// With Source Generator
374+
KeysAccessor.Welcome("aksoftware98", "v4.0")
358375
```
359376

360377

@@ -365,18 +382,9 @@ Check the sample project here to see how to develop a full Blazor WebAssembly pr
365382

366383
[Full Blazor WASM Sample](https://github.com/aksoftware98/multilanguages/tree/master/src/BlazorAKLocalization)
367384

368-
# Upcoming in Version 6.0
385+
# Upcoming in Version 6.1
369386
We are currently working on version 6. Here are the upcoming features.
370-
371-
* [Specify the assembly by name](#specify-the-assembly-by-name)
372-
* [Get all the keys for the current culture](#get-all-the-keys-for-the-current-culture)
373-
* [Use an Enum as a translation key](#use-an-enum-as-a-translation-key)
374-
* [Loop through the key values for the current culture](#loop-through-the-key-values-for-the-current-culture)
375-
* [Get all the registered languages](#get-all-the-registered-languages)
376-
* [Generate a Static Constants Keys File](#generate-a-static-constants-keys-file)
377-
* [Generate an Enum Keys File](#generate-an-enum-keys-file)
378-
* [Verify All Source Code Files Are Localized](#verify-all-source-code-files-are-localized)
379-
* [Verify All Keys Can Be Found](#verify-all-keys-can-be-found)
387+
Verify All Keys Can Be Found](#verify-all-keys-can-be-found)
380388
* [Verify No Unused Keys](#verify-no-unused-keys)
381389
* [Verify No Duplicate Keys](#verify-no-duplicate-keys)
382390

@@ -480,7 +488,7 @@ Example Usage
480488
## Generate a Static Constants Keys File
481489
We are currently working on a CLI but you can also create a static constants file using this method.
482490

483-
```C#
491+
```csharp
484492
var keysProvider = new EmbeddedResourceKeysProvider(Assembly.GetExecutingAssembly());
485493
var languageContainer = new LanguageContainer(CultureInfo.GetCultureInfo("en-US"), keysProvider);
486494
var createCodeLogic = new CreateCodeLogic(languageContainer);
@@ -521,19 +529,19 @@ Here is an example of the usage.
521529
## Generate an Enum Keys File
522530
We are currently working on a CLI but you can also create an enum keys file using this method.
523531

524-
```C#
532+
```csharp
525533
var keysProvider = new EmbeddedResourceKeysProvider(Assembly.GetExecutingAssembly());
526534
var languageContainer = new LanguageContainer(CultureInfo.GetCultureInfo("en-US"), keysProvider);
527-
var createCodeLogic = new CreateCodeLogic(languageContainer);
535+
var codeGeneratorService= new GenerateStaticKeysService(languageContainer);
528536
string namespace = "MyCompany.Project";
529537
string enumName = "LanguageKeys";
530538
string filePath = @"c:\somedirectory\LanguageKeys.cs"
531-
createCodeLogic.CreateEnumKeysFile(namespaceName, enumName, filePath);
539+
codeGeneratorService.CreateEnumKeysFile(namespaceName, enumName, filePath);
532540
```
533541

534542
This will produce a file like this.
535543

536-
```C#
544+
```csharp
537545
//------------------------------------------------------------------------------
538546
// <auto-generated>
539547
// This code was generated by a tool.
@@ -568,7 +576,7 @@ As you are adding and changing Razor files in your your project, you can verify
568576

569577
Example:
570578

571-
```C#
579+
```csharp
572580
/// <summary>
573581
/// If this test is failing it means that there are new strings in your razor file or in your model file Required Attribute that need to be localized.
574582
/// </summary>
@@ -611,7 +619,7 @@ You can verify that there is not a typo in your Razor file for the localization
611619

612620
Example:
613621

614-
```C#
622+
```csharp
615623
/// <summary>
616624
/// If this test is failing it means that you manually typed in a key in your razor file,
617625
/// and it does not exist in the en-US.yml file, or you deleted a key value pair in the en-Us.yml file that was in use.
@@ -655,7 +663,7 @@ Detect if you have keys in your en-US.yml file that are not being used in your r
655663

656664
Example:
657665

658-
```C#
666+
```csharp
659667
/// <summary>
660668
/// If this test is failing, it means that you have keys in your en-US.yml file that are not being used in your razor files.
661669
/// </summary>
@@ -699,7 +707,7 @@ public void VerifyNoUnusedKeys()
699707
In this situation, there are strings that need to be localized but it would result in duplicate keys if automatically created. You might need to manually create the key and values.
700708

701709
Example
702-
```C#
710+
```csharp
703711
/// <summary>
704712
/// If this test is failing it means that there are new strings that need to be localized
705713
/// and if they were to be created automatically, there would be the same key that have different values

0 commit comments

Comments
 (0)