Configuration

This page explains how to configure Translazor in appsettings.json and how to register Translazor services in Program.cs.

For a minimal setup, see the Quickstart.

Basic appsettings.json example

Add a Translazor section to your appsettings.json.

{
  "Translazor": {
    "Translation": {
      "AutoDetectSourceLanguage": false,
      "DefaultSourceLanguage": "en",
      "ThrowIfUnsupportedLanguage": true,
      "FallbackLanguage": "en",
      "SupportedLanguages": [ "ar", "fr" ]
    },
    "AzureSettings": {
      "ApiKey": "YOUR_AZURE_TRANSLATOR_KEY",
      "AzureRegion": "northeurope"
    },
    "Redis": {
      "Host": "YOUR_REDIS_HOST",
      "Port": 14162,
      "User": "default",
      "Password": "YOUR_REDIS_PASSWORD",
      "UseSsl": false
    },
    "CacheOptions": {
      "ExpirationInDays": 222,
      "CacheKey": "Test1"
    },
    "License": {
      "LicenseKey": "LICENSE_KEY_YOU_BOUGHT"
    }
  }
}

Configuration sections

Section	Required	Description
Translazor:Translation	Yes	Main translation behavior, default language, fallback language, and enabled target languages.
Translazor:AzureSettings	Yes when using Azure	Azure Translator API credentials.
Translazor:Redis	No	Redis connection settings. Use this only if you want Redis-based translation caching.
Translazor:CacheOptions	Yes	Cache behavior such as expiration and cache key prefix.
Translazor:License	No	License key for paid Translazor plans. Remove it if you use the free plan.

Translation settings

The Translation section controls the main translation behavior.

{
  "Translazor": {
    "Translation": {
      "AutoDetectSourceLanguage": false,
      "DefaultSourceLanguage": "en",
      "ThrowIfUnsupportedLanguage": true,
      "FallbackLanguage": "en",
      "SupportedLanguages": [ "ar", "fr" ]
    }
  }
}

Setting	Type	Required	Description
AutoDetectSourceLanguage	bool	No	Allows the translation provider to detect the source language automatically. If false, Translazor uses DefaultSourceLanguage.
DefaultSourceLanguage	string	Yes	The original language of your application content. Example: en.
ThrowIfUnsupportedLanguage	bool	No	If true, Translazor can throw an error when an unsupported language is requested. If false, it can fall back instead.
FallbackLanguage	string	Yes	The language used when a selected language is missing, invalid, or cannot be resolved.
SupportedLanguages	string[]	Yes	The target languages enabled in your application.

tip

Start with a small list of supported languages, then add more after you confirm that routing, caching, and SEO metadata work correctly.

Supported languages

SupportedLanguages should contain only the languages you want to enable in your application.

Example:

{
  "SupportedLanguages": [ "ar", "fr", "de", "lt" ]
}

The language codes must be supported by your configured translation provider.

For the full list, see Supported Languages.

Azure Translator settings

The AzureSettings section is required when using Azure Translator.

{
  "Translazor": {
    "AzureSettings": {
      "ApiKey": "YOUR_AZURE_TRANSLATOR_KEY",
      "AzureRegion": "northeurope"
    }
  }
}

Setting	Type	Required	Description
ApiKey	string	Yes	Your Azure Translator API key.
AzureRegion	string	Yes	Your Azure Translator region. Example: northeurope.

warning

Do not commit real API keys to source control. Use user secrets, environment variables, or your hosting provider’s secret management system in production.

Redis settings

The Redis section is optional.

Use Redis if you want translation cache data to be shared between multiple application instances or preserved outside the application memory.

{
  "Translazor": {
    "Redis": {
      "Host": "YOUR_REDIS_HOST",
      "Port": 14162,
      "User": "default",
      "Password": "YOUR_REDIS_PASSWORD",
      "UseSsl": false
    }
  }
}

Setting	Type	Required	Description
Host	string	Yes	Redis server hostname.
Port	int	Yes	Redis server port.
User	string	No	Redis username. Usually default for many hosted Redis providers.
Password	string	No	Redis password. Required if your Redis instance uses authentication.
UseSsl	bool	No	Set to true if your Redis provider requires SSL/TLS.

If you do not use Redis, remove the Redis section and register Translazor with memory cache.

Cache options

The CacheOptions section controls how Translazor stores and identifies cached translations.

{
  "Translazor": {
    "CacheOptions": {
      "ExpirationInDays": 222,
      "CacheKey": "Test1"
    }
  }
}

Setting	Type	Required	Description
ExpirationInDays	int	Yes	Number of days before cached translations expire.
CacheKey	string	Yes	A cache key prefix or identifier used to separate translation cache entries.

tip

Use a stable CacheKey for the same application. Change it only when you intentionally want to separate or reset translation cache data.

License settings

The License section is used for paid plans.

{
  "Translazor": {
    "License": {
      "LicenseKey": "LICENSE_KEY_YOU_BOUGHT"
    }
  }
}

Setting	Type	Required	Description
LicenseKey	string	No	Your Translazor license key. Required for paid features.

If you use the free plan, remove the License section.

Custom section names

You can customize the configuration section names, but the option keys inside each section must keep their default names.

For example, you may rename CacheOptions to MyCacheSettings by setting CacheSectionName in Program.cs:

builder.Services.AddBlazorTranslation(options =>
{
    options.UseConfiguration(builder.Configuration);

    options.CacheSectionName = "MyCacheSettings";

    options.UseMemoryCache();
});

Then your appsettings.json can use:

{
  "Translazor": {
    "MyCacheSettings": {
      "ExpirationInDays": 222,
      "CacheKey": "Test1"
    }
  }
}

However, the option keys must remain unchanged.

For example, these names must stay the same:

ApiKey
AzureRegion
SupportedLanguages
ExpirationInDays
CacheKey
LicenseKey

Program.cs setup

Translazor must be registered in Program.cs.

Always add MemoryCache

This is required for license management and internal cached values.

builder.Services.AddMemoryCache();

Register Translazor with MemoryCache

Use this setup if you do not want to use Redis.

builder.Services.AddMemoryCache();

builder.Services.AddBlazorTranslation(options =>
{
    options.UseConfiguration(builder.Configuration);

    // Optional: use this only if your cache section name is different
    // from the default "CacheOptions".
    options.CacheSectionName = "MyCacheSettings";

    options.UseMemoryCache();
});

If you use the default CacheOptions section name, you can remove this line:

options.CacheSectionName = "MyCacheSettings";

Register Translazor with Redis

Use this setup if you want to store translation cache data in Redis.

builder.Services.AddMemoryCache();

builder.Services.AddBlazorTranslation(options =>
{
    options.UseConfiguration(builder.Configuration);

    // Optional: use this only if your cache section name is different
    // from the default "CacheOptions".
    options.CacheSectionName = "MyCacheSettings";

    options.UseRedis(builder.Configuration);
});

If you use the default CacheOptions section name, you can remove this line:

options.CacheSectionName = "MyCacheSettings";

Minimal configuration for the free plan

If you are using the free plan and memory cache, your configuration can be smaller.

{
  "Translazor": {
    "Translation": {
      "AutoDetectSourceLanguage": false,
      "DefaultSourceLanguage": "en",
      "ThrowIfUnsupportedLanguage": true,
      "FallbackLanguage": "en",
      "SupportedLanguages": [ "ar" ]
    },
    "AzureSettings": {
      "ApiKey": "YOUR_AZURE_TRANSLATOR_KEY",
      "AzureRegion": "northeurope"
    },
    "CacheOptions": {
      "ExpirationInDays": 30,
      "CacheKey": "MyApp"
    }
  }
}

Production recommendations

Before deploying your application to production:

• Keep API keys, Redis passwords, and license keys outside source control.
• Use Redis if your application runs on multiple servers or containers.
• Keep FallbackLanguage set to a language your application always supports.
• Keep SupportedLanguages limited to the languages you really want to expose.
• Use a stable CacheKey per application or environment.
• Use different cache keys for development, staging, and production if they should not share cached translations.

Troubleshooting

Translations are not loading

Check that:

• Translazor:Translation:SupportedLanguages contains the selected language.
• The selected language is supported by your translation provider.
• Azure ApiKey and AzureRegion are correct.
• Translazor services are registered in Program.cs.
• Your cache provider is configured correctly.

Redis is not connecting

Check that:

• Host and Port are correct.
• Password is correct if your Redis provider requires authentication.
• UseSsl matches your Redis provider requirements.
• Your hosting provider allows outbound Redis connections.

Paid features are not available

Check that:

• License:LicenseKey is configured.
• builder.Services.AddMemoryCache() is registered.
• The license key is valid and active.

Related pages

• Quickstart
• Supported Languages
• Language Switching
• Translating Page Content
• Translating Head and SEO Metadata