Skip to content

providers.md

Latest commit

 

History

History
193 lines (138 loc) · 4.66 KB

providers.md

File metadata and controls

193 lines (138 loc) · 4.66 KB
Raw

Providers

DynamicLocalization supports multiple data source providers. This document covers all built-in providers, their options, and format details.

Table of Contents

JsonLocalizationProvider

Loads localized strings from JSON files, embedded resources, or raw JSON strings.

Options

Option Type Default Description
BasePath string "Localization" Directory containing JSON files
FilePattern string "*.json" File matching pattern
UseEmbeddedResources bool false Whether to load from embedded resources
Assembly Assembly? null Assembly containing embedded resources

Modes

File system mode: Loads from {BasePath}/{culture}.json

  • Example: Localization/en.json, Localization/zh-CN.json

Embedded resource mode: Loads from {Assembly}.Localization.{culture}.json

  • Example: MyApp.Localization.en.json, MyApp.Localization.zh-CN.json
  • Requires UseEmbeddedResources = true and Assembly set

JSON Formats

Flat format (simple key-value pairs):

{
  "App.Title": "My App",
  "App.Version": "1.0"
}

Nested format (recommended for organization):

{
  "App": {
    "Title": "My App",
    "Version": "1.0"
  }
}

Both formats produce the same flat keys: App.Title, App.Version.

Loading from String (Programmatic)

var provider = new JsonLocalizationProvider();
provider.LoadJsonString(@"{""App.Title"": ""My App"", ""App.Greeting"": ""Hello""}", "en");
provider.LoadJsonString(@"{""App.Title"": ""我的应用"", ""App.Greeting"": ""你好""}", "zh-CN");

// Then register with CultureService
var cultureService = new CultureService();
cultureService.RegisterProvider(provider);
LocalizationService.Initialize(cultureService);

DI Registration

// File system
services.AddJsonLocalization(options =>
{
    options.BasePath = "Localization";
});

// Embedded resources
services.AddJsonLocalization(options =>
{
    options.UseEmbeddedResources = true;
    options.Assembly = typeof(App).Assembly;
});

YamlLocalizationProvider

Loads localized strings from YAML files or raw YAML strings. Requires the YamlDotNet package.

Options

Option Type Default Description
BasePath string "Localization" Directory containing YAML files
FilePattern string "*.yml" File matching pattern

Modes

File system mode: Loads from {BasePath}/{culture}.yml

  • Example: Localization/en.yml, Localization/zh-CN.yml
  • Also supports .yaml extension by changing FilePattern to "*.yaml"

YAML Formats

Flat format:

App.Title: My App
App.Version: "1.0"

Nested format (recommended):

App:
  Title: My App
  Version: "1.0"
Features:
  HotReload: Hot reload support
  Pluggable: Pluggable provider system

List values are joined with commas:

Items:
  - Apple
  - Banana
  - Cherry

Result: Items = "Apple, Banana, Cherry"

Loading from String (Programmatic)

var provider = new YamlLocalizationProvider();
provider.LoadYamlString("App:\n  Title: My App\n  Greeting: Hello", "en");
provider.LoadYamlString("App:\n  Title: 我的应用\n  Greeting: 你好", "zh-CN");

DI Registration

services.AddYamlLocalization(options =>
{
    options.BasePath = "Localization";
});

ResxLocalizationProvider

Loads localized strings from .resx resource files generated by Visual Studio.

Options

Option Type Default Description
ResourceType Type (required) Type of the RESX resource designer class
AutoDetectCultures bool true Auto-detect available satellite assemblies
KnownCultures string[]? null Manually specify known culture list

Usage

Create RESX files in Visual Studio:

  • Resources/Strings.resx (default/fallback language)
  • Resources/Strings.zh-CN.resx (Chinese)
  • Resources/Strings.ja.resx (Japanese)

DI Registration

services.AddResxLocalization(options =>
{
    options.ResourceType = typeof(Resources.Strings);
});

Culture Fallback

All providers support automatic culture fallback. When a key is not found for the exact culture, it falls back to the parent culture.

Example hierarchy: zh-CN → zh-Hans → zh → invariant

If title exists in zh but not in zh-CN, GetString("title", "zh-CN") will return the value from zh.