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 customIDbResourceStringLocalizer
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:
- Using a standalone
DbResourceConfiguration.json
file - Using
appsettings.json
in aDbResourceProvider
object - Additional ASP.NET Core
IConfiguration
functionality configured (ie. Environment variables, user secrets) - 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, forDataAnnotation
localizationIStringLocalizer
is required in ASP.NET Core (shrug), so generally you'll want to addDbResStringLocalizer
inConfigureServices()
.
© West Wind Technologies, 2006 - 2019 • Updated: 01/24/18
Comment or report problem with topic