Installation for ASP.NET Core

The easiest way to use this library in your own applications is to install the NuGet package into an ASP.NET application.

ASP.NET Core Packages

For ASP.NET Core applications you should install the Westwind.Globalization.AspNetCore which also brings in the base package.

pm> Install-Package Westwind.Globalization.AspNetCore

Download the Localization Admin UI Files

Nuget no longer allows distribution of static content, so in order to use the Localization Admin UI you also need to download and unzip the static Web assets for the Localization Admin UI.

Once you've downloaded the Localization Admin UI zip file, unzip the entire contents into the project's root folder.

For non-Web applications or if you use only the DbRes based localization features, you can just install the base package.

pm> Install-Package Westwind.Globalization

ASP.NET Core Configuration

ASP.NET Core integration works in combination with ASP.NET Core new native Localization features. Westwind.Globalization builds on top of this, or you can just use its native features and it's easy to switch between the two.

West Wind Globalization supports:

  • IStringLocalizer DI via custom IDbResourceStringLocalizer
  • appSettings.json configuration (optional)

Configuration Overview

In order to use Westwind.Globalization you need to point it at a Database that contains the resources. There are a number of configuration settings, but the most important ones are DataProvider which specifies the type of database to use, and the actual ConnectionString.

Configuration can be accomplished in 3 ways:

  1. Using a standalone DbResourceConfiguration.json file
  2. Using appsettings.json in a DbResourceProvider object
  3. Additional ASP.NET Core IConfiguration functionality configured (ie. Environment variables, user secrets)
  4. Explicit configuration via AddWestwindGlobalization(opt => return true)

Configuration values are applied in the order listed, with later assignments over-writing earlier settings.

DbResourceConfiguration

You can create a standalone DbResourceConfiguration.json file for configuration that works both in full framework and .NET Core:

{
  "ResourceAccessMode": "DbResourceManager",
  "ConnectionString": "server=.;database=localizations;integrated security=true;",
  "DataProvider": "SqlServer",
  "ResourceTableName": "Localizations",
  "ResxExportProjectType": "Project",
  "ResxBaseFolder": "~/Properties/",
  "StronglyTypedGlobalResource": "~/Properties/Resources.cs",
  "ResourceBaseNamespace": "AppResources",
  "AddMissingResources": true,
  "LocalizationFormWebPath": "~/LocalizationAdmin/",
  "GoogleApiKey": "XXXfaSyDcvmGhGN7FlynP9QUZOLF8_4K8iF9ChWo",
  "BingClientId": "12345-4b99-47ed-be7e-caf733526020"
}

If this file exists configuration values are read from it.

Copy to Output Directory

If you want to use DbResourceConfiguration.json for configuration storage make sure you set the Copy to Output Directory option to Copy if newer or Copy always to ensure the file is copied into the published output folder.

Make sure you use a Valid Connection String

Make sure the connection string you specify is valid and that you have rights in the database to create new tables. It's best if you pre-create the database that will host the Localization tables. You can use an existing database, just make sure the user running the application has rights to create a new table and dependencies. SqLite will create its own tables locally - again if make sure the Web user has rights to write in the location of the data file.

ASP.NET Core IConfiguration

For ASP.NET Core operation Westwind.Globalization also registers the DbResourceConfiguration instance as IOptions<DbResourceConfiguration> which gives strongly typed access to the configuration via depedency injection.

This means you can use any configured configuration providers - most commonly:

  • appsettings.json using a DbResourceConfiguration object
  • Environment variables
  • User Secrets store

You can store configuration settings in appsettings.json like this:

{
  "Logging": {...},
  "DbResourceConfiguration": {
    "ResourceAccessMode": "DbResourceManager",
    "ConnectionString": "server=.;database=localizations;integrated security=true;",
    "DataProvider": "SqlServer",
    "ResourceTableName": "Localizations",
    "StronglyTypedGlobalResource": "~/Properties/Resources.cs",
    "ResourceBaseNamespace": "AppResources",
    "ResxExportProjectType": "Project",
    "ResxBaseFolder": "~/Properties/",
    "AddMissingResources": true,
    "LocalizationFormWebPath": "~/LocalizationAdmin/",
    "BingClientId": "12345-4b99-47ed-be7e-caf733526020",
    "GoogleApiKey": "XXXfaSyDcvmGhGN7FlynP9QUZOLF8_4K8iF9ChWo"
  }
}

If provided the appsettings.json file overrides DbResourceConfiguration.json.

We recommend you only use one of the files to avoid confusion. For ASP.NET Core projects we recommend you store settings in appsettings.json since that gives you dependency injection for IOptions<DbResourceConfiguration> as well as putting configuration settings into a well-known location.

Enabling West Wind Globalization in ASP.NET Core

You also need to explicitly enable localization features in ASP.NET Core using the following code in the Startup.cs file's ConfigureServices() method:

public void ConfigureServices(IServiceCollection services)
{
    // Standard ASP.NET Localization features are recommended
    // Make sure this is done FIRST!
    services.AddLocalization(options =>
    {
        // I prefer Properties over the default `Resources` folder
        // due to namespace issues if you have a Resources type as
        // most people do for shared resources.
        options.ResourcesPath = "Properties";
    });
    

    // Replace StringLocalizers with Db Resource Implementation
    services.AddSingleton(typeof(IStringLocalizerFactory), 
                          typeof(DbResStringLocalizerFactory));
    services.AddSingleton(typeof(IHtmlLocalizerFactory),
                          typeof(DbResHtmlLocalizerFactory));
                          
    
    // Required: Enable Westwind.Globalization (opt parm is optional)
    // shown here with optional manual configuration code
    services.AddWestwindGlobalization(opt =>
    {                
        // the default settings comme from DbResourceConfiguration.json if exists
        // you can override the settings here, the config you create is added
        // to the DI system (DbResourceConfiguration)

        // Resource Mode - from Database (or Resx for serving from Resources)
        opt.ResourceAccessMode = ResourceAccessMode.DbResourceManager;  // .Resx
        
        // Make sure the database you connect to exists
        opt.ConnectionString = "server=.;database=localizations;uid=localizations;pwd=local";
        
        // Database provider used - Sql Server is the default
        opt.DataProvider = DbResourceProviderTypes.SqlServer;

        // The table in which resources are stored
        opt.ResourceTableName = "localizations";
        
        opt.AddMissingResources = false;
        opt.ResxBaseFolder = "~/Properties/";

        // Set up security for Localization Administration form
        opt.ConfigureAuthorizeLocalizationAdministration(actionContext =>
        {
            // return true or false whether this request is authorized
            return true;   //actionContext.HttpContext.User.Identity.IsAuthenticated;
        });

    });

    ...
    
    services.AddMvc();
}

Any code changes made override any of the file values. You can also replace the entire DbResourceConfiguration object entirely in this handler.

In addition you probably will want to add standard ASP.NET Core Localization features to the Configure() method in Startup.cs:

public void Configure(IApplicationBuilder app) 
{
    ..
  
    var supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("en"),
        new CultureInfo("de-DE"),
        new CultureInfo("de"),
        new CultureInfo("fr")
    };
    app.UseRequestLocalization(new RequestLocalizationOptions
    {
        DefaultRequestCulture = new RequestCulture("en-US"),
        SupportedCultures = supportedCultures,
        SupportedUICultures = supportedCultures                 
    });
}

Dependency Injection for DbResourceConfiguration

You can get access to DbResourceConfiguration in a number of ways:

  • Via DI by asking for DbResourceConfiguration
  • Via DI by asking for IOptions<DbResourceConfig> (if loaded through IConfiguration)
  • Static DbResourceConfiguration.Current

Dependency Injection for IDbResStringLocalizer

One of the base features of ASP.NET Core's Localization is IStringLocalizer which provides the provides an interface to map type signatures to instances of Resx resources. DbResStringLocalizer uses the DbResourceManager (which supports switchable Db or Resx resource access).

To use the DbRes localizer, override the default IStringLocalizer with:

services.AddSingleton(typeof(IStringLocalizerFactory), typeof(DbResStringLocalizerFactory));

Use of IStringLocalizer is optional.

You can use DbRes.T() or strongly typed resources directly if you prefer. However, for DataAnnotation localization IStringLocalizer is required in ASP.NET Core (shrug), so generally you'll want to add DbResStringLocalizer in ConfigureServices().

© West Wind Technologies, 2006 - 2019 • Updated: 01/24/18
Comment or report problem with topic