Merge branch 'master' of https://github.com/valdisiljuconoks/Localiza…

…tionProvider.git

README.md

@@ -1,13 +1,179 @@
 ## What is LocalzationProvider project?
 
-LocalizationProvider project is attempt to improve EPiServer built-in localization provider.
+LocalizationProvider project is an attempt to improve EPiServer built-in localization provider originally based on collection of Xml files.
+
 Giving you following features:
 * Database driven localization provider for EPiServer
 * Administration UI for editors to change or add new translations for required languages
-* Possibility to add new localization messages for resources for while adding new language to the EPiServer site without involving a developer
+* Possibility to add new localized messages while adding new language to the EPiServer site without involving the developer
 * Easy migration tool from built-in default Xml files to your EPiServer database
 
+Localization Provider consists from few components:
+
+* `DbLocalizationProvider` - this is core package and gives you EPiServer localization provider, `DataAnnotation` attributes, model and resource synchronization process and other core features.
+* `DbLocalizationProvider.AdminUI` - administrator user interface for editors and administrators to overview resources, make translations, import / export and do other management stuff.
+* `DbLocalizationProvider.MigrationTool` - tool gives you possibility to generate JSON format data out of Xml language files later to import these resources into this new DbLocalizationProvider.
+
+
+### Installing Provider
+
+Installation nowadays can't be more simpler as just adding NuGet package(s).
+
+```
+PM> Install-Package DbLocalizationProvider
+PM> Install-Package DbLocalizationProvider.AdminUI
+PM> Install-Package DbLocalizationProvider.MigrationTool
+```
+
+**NB!** Currently `DbLocalizationProvider` NuGet package has naïve `web.config` transformation file assuming that `<episerver.framework>` section is not extracted into separate file (this was usual case for older versions of AlloyTech sample sites).
+
+New localization provider needs to be "registered" and added to the list of the localization providers configured for EPiServer Framework. Section may look like this:
+
+```xml
+<episerver.framework>
+  ..
+  <localization>
+    <providers>
+      <add name="db"
+           type="DbLocalizationProvider.DatabaseLocalizationProvider, DbLocalizationProvider" />
+      <add name="languageFiles" virtualPath="~/lang"
+           type="EPiServer.Framework.Localization.XmlResources.FileXmlLocalizationProvider, EPiServer.Framework" />
+    </providers>
+  </localization>
+  ..
+</episerver.framework>
+```
+
+**NB!** If you do have extracted `<episerver.framework>` section into separate file (usually `episerver.framework.config`), please clean-up web.config after NuGet package installation and move content of the `<localization>` section to that separate physical file.
+
+## Import Language Xml Files
+
+This is a natural situation when adding `DbLocalizationProvider` to the project - there already will be Xml language files present.
+
+Even after `DbLocalizationProvider` library is added - old Xml language files will continue to work. However - if you would like to get rid of language files completely - you will need to migrate them to the database.
+
+Migration may happen in 2 ways:
+
+* via SQL script generated by migration tool
+* sometimes direct access (via `SqlConnection` object) may not be applicable. That's why it's possible to extract all Xml language file resources and later import them into database via Administration UI (AdminUI).
+
+
+### Migration with SQL script
+
+Migration via SQL script is pretty simple. First of all you need to install `DbLocalizationProvider.MigrationTool` package. Then you can execute `.exe` file inside package `tools/` folder.
+
+
+```
+> DbLocalizationProvider.MigrationTool.exe -s="{path-to-project}" -e -i
+```
+
+Explanation of switches used:
+
+* `-s` - specifies **s**ource directory for the project (your web root)
+* `-e` - asks migration tool to **e**xport all resources from language Xml files into SQL format file (resulting file `localization-resource-translations.sql` by default is located in the same folder specified by `-s`)
+* `-i` - asks migration tool to **i**mport resources from exported file into directly database (using connection string named `"EPiServerDB"`)
+
+### Migration via JSON file
+
+Using JSON format export file is similar as with SQL script file, you just need to provide switch to use JSON file (import from AdminUI is supported only with JSON format files).
+
+
+```
+> DbLocalizationProvider.MigrationTool.exe -s="{path-to-project}" -e --json
+```
+
+
+## DbLocalizationProvider Features
+
+All resources in DbLocalizationProvider system are divided into 2 groups:
+
+* **Resources** - localized resources are just list of key / value pairs. You may have a key for the resource and value is its translation in specific language. Resources are designed as just POCO objects.
+* **Models** - models are usually view models that may have `DataAnnotation` attributes attached to them (like, `Display`, `Required`, etc).
+
+
+### Localized Resources
+
+Localized resource is straight forward way to define list of properties that are localizable. Localized resource is simple POCO class that defines list of properties:
+
+```csharp
+namespace MySampleProject {
+
+    [LocalizedResource]
+    public class MyResources
+    {
+        public static string SampleResource => "This is default value";
+    }
+}
+```
+
+
+Now, you may use one of the ways to output this resource to the end-users:
+
+```
+@using DbLocalizationProvider
+
+<div>
+    @Html.Translate(() => MyResources.SampleResource)
+</div>
+```
+
+
+### Localized Models
+
+Another more interesting way and usage is to define localizable view models.
+
+Localizable view model means that `DbLocalizationProvider` library will search for `[LocalizedModel]` attributes and will discover all models and further discovery of the resources there.
+
+Now you may define following view model:
+
+```csharp
+namespace MySampleProject {
+
+    [LocalizedModel]
+    public class MyViewModel
+    {
+        [Display(Name = "This is default value")]
+        public string SampleProperty { get; set; }
+    }
+}
+```
+
+### Localized Model Data Annotations
+
+Usually view models are decorated with various `DataAnnotation` attributes to get model validation into the Asp.Net Mvc request processing pipeline. Which is very fine and `DbLocalizationProvider` aware of these attributes once scanning for localized models.
+
+So if you add bit more attributes to initial view model:
+
+```csharp
+namespace MySampleProject {
+
+    [LocalizedModel]
+    public class MyViewModel
+    {
+        [Display(Name = "This is default value")]
+        [Required]
+        [StringLength(5)]
+        public string SampleProperty { get; set; }
+    }
+}
+```
+
+Following resources will be discovered:
+
+```
+MySampleProject.MyViewModel.SampleProperty
+MySampleProject.MyViewModel.SampleProperty-Required
+MySampleProject.MyViewModel.SampleProperty-StringLength
+```
+
+Which gives you a possibility to translation precise error messages shown when particular property has invalid value for this model.
+
+So you can easily continue using Html helper extensions like:
 
-### Getting Started
 
-### Migrating from Xml files to Database
+```
+<div>
+    @Html.LabelFor(m => m.SampleProperty)
+    @Html.EditorFor(m => m.SampleProperty)
+</div>
+```