Installation and Configuration - RickStrahl/Westwind.Globalization GitHub Wiki

The easiest way to use data driven resources with this library is to install the NuGet package into an ASP.NET application.

For Web projects the recommended package to start with is:

pm> Install-Package Westwind.Globalization.Web.Starter

This installs the required assemblies, adds a few configuration entries in web.config and enables the resource provider by default, and adds the localization administration Web Resources Editor so you can create the resource table and manage resources in it.

The starter package also adds a few sample resources and a couple of test pages to check operation of the providers and see localization work. The starter package can be removed once you're up and running leaving the dependencies in place.

You can also install the Web only package directly:

pm> Install-Package Westwind.Globalization.Web

The Web package includes ASP.NET Resource Providers, support for WebForms meta:resource providers as well as the localization administration Web Resource Editor.

If you are using this library in a non-Web application or an MVC/Web API application that doesn't require the Web Resource Editor you can use just the core package.

pm> Install-Package Westwind.Globalization

The key configuration items set are the DbResourceConfiguration section in the config file which tells the provider where to find the database resources:

<configuration>
  <configSections>
    <section name="DbResourceConfiguration" requirePermission="false" 
			 type="System.Configuration.NameValueSectionHandler,System,Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
  </configSections>  

  <DbResourceConfiguration>
    <add key="ConnectionString" value="server=.;database=Localizations;integrated security=true;" />
    <add key="ResourceTableName" value="Localizations" />
    <add key="AddMissingResources" value="True" />

    <!-- Resource Imports and Exports -->
    <add key="ResxExportProjectType" value="Project" />
    <add key="StronglyTypedGlobalResource" value="~/App_Code/Resources.cs" />
    <add key="ResourceBaseNamespace" value="AppResources" />    
    <add key="ResxBaseFolder" value="~/" />

	<add key="LocalizationFormWebPath" value="~/LocalizationAdmin/" />
    
    <!-- Bing Translation -->
    <add key="BingClientId" value="" />
    <add key="BingClientSecret" value="" />    
  </DbResourceConfiguration>

  <!-- Enable ASP.NET Resource Provider  -->
  <globalization resourceProviderFactoryType=
     "Westwind.Globalization.DbSimpleResourceProviderFactory,Westwind.Globalization.Web" />
</configuration>

ConnectionString and ResourceTableName
The two most important keys are the connectionString and resourceTableName which point at your database and a table that holds resources. You can use either a raw connection string as above or a connection string name in the <ConnectionStrings> section of your config file.

AddMissingResources When set to true causes any resource lookup that fails to produce matching resource ID to write the invariant resource into the database. Use with caution - as this might slow down your application significantly as you now write to the database on any missing resources. Use only during development and testing to get resources into the system for easier debugging later.

ResxExportProjectType
This option determines how the Resx export feature works. The two options are Project or WebForms. Project exports all resource files into the folder specified by the ResxBaseFolder (or what you select in the Export Resources Dialog). For any non-WebForms project use Project mode. WebForms writes resources into folder specific App_LocalResources and App_GlobalResources folders based on the root folder.

ResxBaseFolder
The base folder that's used for all Resx Import and Export operations. The default is ~/ which is the root web folder, but you can specify a full OS path here. Note that this allows you to read/write resources in other non-web projects - as long as your Web application has writes to the folder specified.

StronglyTypeGlobalResource and ResourceBaseNamespace
If you do a strongly typed class export from the admin manager all resources will be created in a single file in the this file using the ResourceBaseNameSpace as the namespace in the generated class.

LocalizationFormWebPath This path specifies the path to the Web Resource Editor. The default value for this works for the installed location - change this value if you decide to move the admin interface in your project to a different location.

The default configuration format using .NET .config flies is shown above. If your application/web account has rights to write to the .config file, the configuration information is created automatically the first time you start up the application (except the <globalization> section. These config section has standard .NET behavior with auto-restarting on change in web.config.

Configuration information can also be stored in plain Json or Xml files by explicitly setting the configuration provider during startup (in Application_Load or during app startup code):

DbResourceConfiguration.ConfigurationMode = ConfigurationModes.JsonFile;
//DbResourceConfiguration.ConfigurationMode = ConfigurationModes.XmlFile;

These files are external and do not automatically cause an app restart when changed.

In order to use database resources you'll actually have to create some resources in a database. Make sure you've added a valid connection string in the .config file in the last step! Then open /LocalizationAdmin/ in your browser and click on the Create Table button in the toolbar.

Once the table's been created you can now start creating resources interactively using the Web Resource Editor UI. You can also directly add values to the database table, or use the DbResourceDataManager API to manipulate the data programmatically.

By default a Resources ResourceSet has been created for you with resources that are used in the test page. You can remove those resources or the resource set as needed once you know the provider works. ResourceSets are logical groups of resources that belong together - I like to use one ResourceSet per form or per application feature depending on how much content is involved. But you can also use a single ResourceSet for your entire application if you want. Whatever works for you to make it easy to group and find resources.

I also recommend that you first perform an Import Resx step to pull any existing Resx resources in your project into the application. This will also import the LocalizationForm resources into your database so that the localization form properly localizes from database resources.