引言：理解网站国际化的重要性
在全球化时代，网站国际化（Internationalization，简称i18n）已成为现代Web开发的必备技能。ASP.NET作为微软的核心Web框架，提供了强大的本地化支持，但许多开发者在实际项目中仍会遇到配置复杂、编码问题频发等挑战。本文将从零开始，详细讲解如何在ASP.NET网站中实现完整的多语言支持，并深入解决常见的编码问题。
为什么需要国际化？
国际化不仅仅是翻译文本，它涉及日期格式、货币符号、数字表示、排序规则等多个维度。一个支持多语言的网站能够：
扩大用户群体，覆盖全球市场
提升用户体验，增强用户粘性
符合地区法规要求（如欧盟的多语言要求）
提高SEO效果，在不同地区的搜索引擎中获得更好排名
第一部分：ASP.NET国际化基础架构
1.1 ASP.NET本地化核心组件
ASP.NET框架提供了三个核心的本地化组件：
ResourceManager
：负责资源文件的加载和管理
CultureInfo
：定义区域性和文化相关的设置
ResourceFile
（.resx）：存储键值对的资源文件
1.2 资源文件结构设计
在ASP.NET Core中，推荐使用以下目录结构：
Resources/
├── Controllers/
│ ├── HomeController.en-US.resx
│ ├── HomeController.zh-CN.resx
│ └── HomeController.ja-JP.resx
├── Views/
│ ├── Home/
│ │ ├── Index.en-US.resx
│ │ ├── Index.zh-CN.resx
│ │ └── Index.ja-JP.resx
│ └── Shared/
│ ├── Layout.en-US.resx
│ ├── Layout.zh-CN.resx
│ └── Layout.ja-JP.resx
└── Models/
├── ValidationMessages.en-US.resx
├── ValidationMessages.zh-CN.resx
└── ValidationMessages.ja-JP.resx
第二部分：从零开始配置多语言支持
2.1 创建ASP.NET Core项目
首先，创建一个空的ASP.NET Core项目：
dotnet new web -n MultilingualWebApp
cd MultilingualWebApp
2.2 添加必要的NuGet包
dotnet add package Microsoft.Extensions.Localization
dotnet add package Microsoft.AspNetCore.Localization
2.3 配置Program.cs（ASP.NET Core 6+）
在Program.cs中添加本地化服务：
using Microsoft.AspNetCore.Localization;
using Microsoft.Extensions.Localization;
using System.Globalization;

var builder = WebApplication.CreateBuilder(args);

// 1. 添加本地化服务
builder.Services.AddLocalization(options => options.ResourcesPath = “Resources”);

// 2. 配置支持的文化
var supportedCultures = new[]
{
new CultureInfo(“en-US”),
new CultureInfo(“zh-CN”),
new CultureInfo(“ja-JP”),
new CultureInfo(“fr-FR”)
};

// 3. 配置请求本地化中间件
builder.Services.Configure(options =>
{
options.DefaultRequestCulture = new RequestCulture(“en-US”);
options.SupportedCultures = supportedCultures;
options.SupportedUICultures = supportedCultures;

// 4. 配置确定文化的方式（按优先级）
options.RequestCultureProviders = new List
{
new QueryStringRequestCultureProvider(), // URL参数: ?culture=zh-CN&ui-culture=zh-CN
new CookieRequestCultureProvider(), // Cookie存储
new AcceptLanguageHeaderRequestCultureProvider() // 浏览器Accept-Language头
};
});

var app = builder.Build();

// 5. 使用请求本地化中间件
app.UseRequestLocalization();

app.MapGet(“/”, () => “Hello World!”);

app.Run();
2.4 创建资源文件
在项目根目录创建Resources文件夹，并添加以下资源文件：
Resources/Controllers/HomeController.resx
（默认资源）



Welcome to our website


Home Page


Resources/Controllers/HomeController.zh-CN.resx
（简体中文）



欢迎访问我们的网站


首页


Resources/Controllers/HomeController.ja-JP.resx
（日语）



当サイトへようこそ


ホームページ


2.5 创建控制器使用本地化
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;

namespace MultilingualWebApp.Controllers
{
public class HomeController : Controller
{
private readonly IStringLocalizer _localizer;

public HomeController(IStringLocalizer localizer)
{
_localizer = localizer;
}

public IActionResult Index()
{
// 获取本地化字符串
ViewBag.WelcomeMessage = _localizer[“WelcomeMessage”];
ViewBag.PageTitle = _localizer[“PageTitle”];

// 获取当前文化信息
var currentCulture = System.Globalization.CultureInfo.CurrentCulture.Name;
ViewBag.CurrentCulture = currentCulture;

return View();
}

// 演示带参数的本地化
public IActionResult Greeting(string name)
{
// 在资源文件中添加: GreetingMessage = “Hello, {0}!”
// 在 zh-CN 中: GreetingMessage = “你好，{0}！”
ViewBag.Message = _localizer[“GreetingMessage”, name];
return View();
}
}
}
2.6 创建视图
Views/Home/Index.cshtml
@{
ViewData[“Title”] = ViewBag.PageTitle;
}

@ViewBag.WelcomeMessage

Views/Home/Greeting.cshtml
@{
ViewData[“Title”] = “Greeting”;
}

@ViewBag.Message

← Back to Home
2.7 运行和测试
dotnet run
访问
https://localhost:5001
，然后通过URL参数切换语言：
https://localhost:5001/?culture=en-US
https://localhost:5001/?culture=zh-CN
https://localhost:5001/?culture=ja-JP
第三部分：高级本地化技术
3.1 使用View Localizer
在视图中直接使用本地化：
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer

@Localizer[“WelcomeMessage”]

@Localizer[“Introduction”, “ASP.NET”]

3.2 数据注解本地化
创建模型和对应的资源文件：
// Models/User.cs
using System.ComponentModel.DataAnnotations;

public class User
{
[Required(ErrorMessage = “Name is required”)]
[Display(Name = “User Name”)]
public string Name { get; set; }

[EmailAddress(ErrorMessage = “Invalid email format”)]
[Display(Name = “Email Address”)]
public string Email { get; set; }
}
Resources/Models/ValidationMessages.resx



The {0} field is required.


The {0} field is not a valid e-mail address.


User Name


Resources/Models/ValidationMessages.zh-CN.resx



{0} 字段是必填的。


{0} 字段不是有效的电子邮件地址。


用户名


3.3 自定义中间件实现Cookie语言切换
创建语言切换中间件：
// Middleware/SetLanguageMiddleware.cs
using Microsoft.AspNetCore.Http;
using System.Globalization;
using System.Threading.Tasks;

public class SetLanguageMiddleware
{
private readonly RequestDelegate _next;

public SetLanguageMiddleware(RequestDelegate next)
{
_next = next;
}

public async Task InvokeAsync(HttpContext context)
{
// 检查URL参数中的语言设置
var languageQuery = context.Request.Query[“culture”];
if (!string.IsNullOrEmpty(languageQuery))
{
var culture = new CultureInfo(languageQuery);
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;

// 保存到Cookie，有效期1年
context.Response.Cookies.Append(
“UserCulture”,
languageQuery,
new CookieOptions
{
Expires = DateTimeOffset.UtcNow.AddYears(1),
IsEssential = true,
Path = “/”
});
}
// 如果没有URL参数，检查Cookie
else if (context.Request.Cookies.ContainsKey(“UserCulture”))
{
var culture = context.Request.Cookies[“UserCulture”];
if (!string.IsNullOrEmpty(culture))
{
var cultureInfo = new CultureInfo(culture);
CultureInfo.CurrentCulture = cultureInfo;
CultureInfo.CurrentUICulture = cultureInfo;
}
}

await _next(context);
}
}
在Program.cs中注册：
app.UseMiddleware();
第四部分：解决常见编码问题
4.1 问题1：资源文件编码导致的乱码
问题描述
：当资源文件包含中文、日文等非ASCII字符时，可能出现乱码。
解决方案
：
确保资源文件使用UTF-8编码
：
在Visual Studio中，右键资源文件 → 属性 → 高级 → 编码：选择”Unicode (UTF-8)”
或者在创建.resx文件时指定编码：
// 创建资源文件时的正确编码方式
using System.Resources;
using System.Reflection;

var resourceManager = new ResourceManager(“Resources”, Assembly.GetExecutingAssembly());
在.csproj中明确指定编码
：


net6.0
$(DefaultItemExcludes);**/*.resx

ResXFileCodeGenerator
%(Filename).designer.cs



4.2 问题2：URL参数编码问题
问题描述
：当URL中包含中文参数时，可能出现编码问题。
解决方案
：
// 在控制器中正确处理编码
public IActionResult Search(string keyword)
{
// 确保正确解码
var decodedKeyword = Uri.UnescapeDataString(keyword ?? “”);

// 或者在路由配置中指定
// app.MapGet(“/search/{keyword}”, async (string keyword) => { … });

return Content($”搜索关键词: {decodedKeyword}”);
}

// 在视图中生成URL时正确编码
搜索
4.3 问题3：数据库内容的多语言存储
问题描述
：如何存储和查询多语言数据。
解决方案1：每语言一个字段
CREATE TABLE Products (
Id INT PRIMARY KEY,
Name_en NVARCHAR(200),
Name_zh NVARCHAR(200),
Name_ja NVARCHAR(200),
Description_en NVARCHAR(MAX),
Description_zh NVARCHAR(MAX),
Description_ja NVARCHAR(MAX)
);
解决方案2：单独的语言表
CREATE TABLE Products (
Id INT PRIMARY KEY,
SKU NVARCHAR(50)
);

CREATE TABLE ProductTranslations (
ProductId INT,
LanguageCode NVARCHAR(10),
Name NVARCHAR(200),
Description NVARCHAR(MAX),
PRIMARY KEY (ProductId, LanguageCode),
FOREIGN KEY (ProductId) REFERENCES Products(Id)
);
C#代码实现
：
public class ProductService
{
private readonly ApplicationDbContext _context;
private readonly IHttpContextAccessor _httpContextAccessor;

public ProductService(ApplicationDbContext context, IHttpContextAccessor httpContextAccessor)
{
_context = context;
_httpContextAccessor = httpContextAccessor;
}

public async Task> GetProductsAsync()
{
var currentCulture = _httpContextAccessor.HttpContext?.Request.Cookies[“UserCulture”]
?? “en-US”;

return await _context.Products
.Include(p => p.Translations.Where(t => t.LanguageCode == currentCulture))
.Select(p => new Product
{
Id = p.Id,
Name = p.Translations.FirstOrDefault(t => t.LanguageCode == currentCulture).Name ?? p.Name,
Description = p.Translations.FirstOrDefault(t => t.LanguageCode == currentCulture).Description ?? p.Description
})
.ToListAsync();
}
}
4.4 问题4：日期、数字和货币格式化
问题描述
：不同地区的日期、数字格式差异很大。
解决方案
：
// 在视图中格式化
@using System.Globalization

@{
var date = DateTime.Now;
var number = 1234567.89;
var price = 99.99m;
}

美国日期: @date.ToString(“d”, new CultureInfo(“en-US”))

美国数字: @number.ToString(“N”, new CultureInfo(“en-US”))

美国货币: @price.ToString(“C”, new CultureInfo(“en-US”))

中国日期: @date.ToString(“d”, new CultureInfo(“zh-CN”))

中国数字: @number.ToString(“N”, new CultureInfo(“zh-CN”))

中国货币: @price.ToString(“C”, new CultureInfo(“zh-CN”))

德国日期: @date.ToString(“d”, new CultureInfo(“de-DE”))

德国数字: @number.ToString(“N”, new CultureInfo(“de-DE”))

德国货币: @price.ToString(“C”, new CultureInfo(“de-DE”))

在控制器中
：
public IActionResult FormatExample()
{
var currentCulture = CultureInfo.CurrentCulture;

ViewBag.Date = DateTime.Now.ToString(“d”, currentCulture);
ViewBag.Number = 1234567.89.ToString(“N”, currentCulture);
ViewBag.Currency = 99.99m.ToString(“C”, currentCulture);

return View();
}
4.5 问题5：SEO友好的URL结构
问题描述
：如何在保持SEO友好的同时支持多语言URL。
解决方案
：
// Program.cs 配置路由
app.MapControllerRoute(
name: “localizedDefault”,
pattern: “{culture}/{controller=Home}/{action=Index}/{id?}”,
constraints: new { culture = “en-US|zh-CN|ja-JP” });

app.MapControllerRoute(
name: “default”,
pattern: “{controller=Home}/{action=Index}/{id?}”);

// 自定义路由约束验证文化
public class CultureConstraint : IRouteConstraint
{
private readonly string[] _validCultures;

public CultureConstraint(params string[] validCultures)
{
_validCultures = validCultures;
}

public bool Match(
HttpContext httpContext,
IRouter route,
string routeKey,
RouteValueDictionary values,
RouteDirection routeDirection)
{
if (!values.TryGetValue(routeKey, out var routeValue))
return false;

var culture = routeValue?.ToString();
return _validCultures.Contains(culture);
}
}
URL示例
：
https://example.com/en-US/products/123
https://example.com/zh-CN/products/123
https://example.com/ja-JP/products/123
4.6 问题6：异步操作中的文化上下文丢失
问题描述
：在异步操作中，CultureInfo可能丢失或重置。
解决方案
：
public async Task AsyncOperation()
{
// 保存当前文化
var currentCulture = CultureInfo.CurrentCulture;
var currentUICulture = CultureInfo.CurrentUICulture;

await Task.Run(async () =>
{
// 在异步上下文中恢复文化
CultureInfo.CurrentCulture = currentCulture;
CultureInfo.CurrentUICulture = currentUICulture;

// 执行异步操作
await Task.Delay(1000);

// 现在可以安全地使用本地化
var message = _localizer[“AsyncMessage”];
});

return Ok();
}

// 或者使用AsyncLocal保持上下文
private static readonly AsyncLocal _currentCulture = new AsyncLocal();

public async Task AsyncOperationWithContext()
{
_currentCulture.Value = CultureInfo.CurrentCulture;

await Task.Run(async () =>
{
// 从AsyncLocal恢复
if (_currentCulture.Value != null)
{
CultureInfo.CurrentCulture = _currentCulture.Value;
}

await DoWork();
});

return Ok();
}
第五部分：最佳实践和性能优化
5.1 资源文件组织最佳实践
按功能模块组织
：
Resources/
├── Features/
│ ├── Authentication/
│ │ ├── Login.resx
│ │ └── Register.resx
│ └── Dashboard/
│ ├── Overview.resx
│ └── Statistics.resx
使用命名空间约定
：
// 在Startup.cs或Program.cs中配置
builder.Services.AddLocalization(options =>
{
options.ResourcesPath = “Resources”;
});

// 使用时指定完整类型名
public class LoginController : Controller
{
private readonly IStringLocalizer _localizer;
// 资源文件路径: Resources/Features/Authentication/LoginController.resx
}
5.2 缓存策略
// 自定义本地化缓存
public class CachedStringLocalizer : IStringLocalizer
{
private readonly IStringLocalizer _innerLocalizer;
private readonly IMemoryCache _cache;
private static readonly TimeSpan CacheDuration = TimeSpan.FromHours(1);

public CachedStringLocalizer(IStringLocalizer innerLocalizer, IMemoryCache cache)
{
_innerLocalizer = innerLocalizer;
_cache = cache;
}

public LocalizedString this[string name]
{
get
{
var cacheKey = $”loc:{CultureInfo.CurrentCulture.Name}:{name}”;
return _cache.GetOrCreate(cacheKey, entry =>
{
entry.AbsoluteExpirationRelativeToNow = CacheDuration;
return _innerLocalizer[name];
});
}
}

public LocalizedString this[string name, params object[] arguments]
{
get
{
var cacheKey = $”loc:{CultureInfo.CurrentCulture.Name}:{name}:{string.Join(“|”, arguments)}”;
return _cache.GetOrCreate(cacheKey, entry =>
{
entry.AbsoluteExpirationRelativeToNow = CacheDuration;
return _innerLocalizer[name, arguments];
});
}
}

public IEnumerable GetAllStrings(bool includeParentCultures)
{
return _innerLocalizer.GetAllStrings(includeParentCultures);
}
}
5.3 监控和日志
public class LocalizedStringLogger : IStringLocalizer
{
private readonly IStringLocalizer _innerLocalizer;
private readonly ILogger _logger;

public LocalizedStringLogger(IStringLocalizer innerLocalizer, ILogger logger)
{
_innerLocalizer = innerLocalizer;
_logger = logger;
}

public LocalizedString this[string name]
{
get
{
var result = _innerLocalizer[name];
if (result.ResourceNotFound)
{
_logger.LogWarning($”Missing localization for ‘{name}’ in culture {CultureInfo.CurrentCulture.Name}”);
}
return result;
}
}

public LocalizedString this[string name, params object[] arguments]
{
get
{
var result = _innerLocalizer[name, arguments];
if (result.ResourceNotFound)
{
_logger.LogWarning($”Missing localization for ‘{name}’ in culture {CultureInfo.CurrentCulture.Name}”);
}
return result;
}
}

public IEnumerable GetAllStrings(bool includeParentCultures)
{
return _innerLocalizer.GetAllStrings(includeParentCultures);
}
}
第六部分：测试和验证
6.1 单元测试本地化
using Microsoft.Extensions.Localization;
using Moq;
using Xunit;

public class LocalizationTests
{
[Fact]
public void TestChineseLocalization()
{
// 模拟中文环境
var culture = new CultureInfo(“zh-CN”);
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;

// 创建模拟的本地化器
var mockLocalizer = new Mock();
mockLocalizer.Setup(l => l[“WelcomeMessage”])
.Returns(new LocalizedString(“WelcomeMessage”, “欢迎访问我们的网站”));

// 验证
var result = mockLocalizer.Object[“WelcomeMessage”];
Assert.Equal(“欢迎访问我们的网站”, result.Value);
}

[Fact]
public void TestFallbackBehavior()
{
// 测试当特定语言资源不存在时的回退行为
var culture = new CultureInfo(“fr-FR”); // 假设没有法语资源
CultureInfo.CurrentCulture = culture;
CultureInfo.CurrentUICulture = culture;

// 应该回退到默认资源（英语）
var mockLocalizer = new Mock();
mockLocalizer.Setup(l => l[“WelcomeMessage”])
.Returns(new LocalizedString(“WelcomeMessage”, “Welcome to our website”));

var result = mockLocalizer.Object[“WelcomeMessage”];
Assert.Equal(“Welcome to our website”, result.Value);
}
}
6.2 集成测试
public class LocalizationIntegrationTests : IClassFixture>
{
private readonly WebApplicationFactory _factory;

public LocalizationIntegrationTests(WebApplicationFactory factory)
{
_factory = factory;
}

[Theory]
[InlineData(“en-US”, “Welcome to our website”)]
[InlineData(“zh-CN”, “欢迎访问我们的网站”)]
[InlineData(“ja-JP”, “当サイトへようこそ”)]
public async Task Get_EndpointsReturnTranslatedContent(string culture, string expectedContent)
{
// Arrange
var client = _factory.CreateClient();
var request = new HttpRequestMessage(HttpMethod.Get, $”/?culture={culture}”);

// Act
var response = await client.SendAsync(request);
var content = await response.Content.ReadAsStringAsync();

// Assert
Assert.Contains(expectedContent, content);
}
}
第七部分：部署和维护
7.1 CI/CD中的资源文件处理
# .github/workflows/deploy.yml
name: Deploy Multilingual App

on:
push:
branches: [ main ]

jobs:
deploy:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v2

– name: Setup .NET
uses: actions/setup-dotnet@v1
with:
dotnet-version: ‘6.0.x’

– name: Restore dependencies
run: dotnet restore

– name: Build
run: dotnet build –configuration Release

– name: Run localization tests
run: dotnet test –filter “Category=Localization”

– name: Publish
run: dotnet publish -c Release -o publish

– name: Deploy to Azure
run: |
az webapp deploy –resource-group MyResourceGroup \
–name MyWebApp \
–src-path publish \
–type zip
7.2 监控缺失的翻译
// 在生产环境中监控缺失的翻译
public class LocalizationMonitoringMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger _logger;

public LocalizationMonitoringMiddleware(RequestDelegate next, ILogger logger)
{
_next = next;
_logger = logger;
}

public async Task InvokeAsync(HttpContext context)
{
var originalBody = context.Response.Body;
using var responseBody = new MemoryStream();
context.Response.Body = responseBody;

await _next(context);

// 检查响应中是否包含未翻译的标记
responseBody.Position = 0;
var responseBodyText = await new StreamReader(responseBody).ReadToEndAsync();

if (responseBodyText.Contains(“RESX_NOT_FOUND”))
{
_logger.LogError($”Missing localization detected for URL: {context.Request.Path}”);
}

context.Response.Body = originalBody;
await context.Response.WriteAsync(responseBodyText);
}
}
结论
ASP.NET的国际化支持虽然强大，但需要正确的配置和最佳实践才能发挥最大效果。通过本文的详细指南，您应该能够：
✅ 从零开始配置ASP.NET Core的多语言支持
✅ 正确处理各种编码问题
✅ 实现高级本地化功能（数据注解、视图本地化等）
✅ 解决常见的国际化挑战
✅ 应用最佳实践优化性能和维护性
记住，成功的国际化不仅仅是技术实现，更需要良好的规划、持续的维护和对用户体验的深入理解。建议在项目初期就规划好国际化策略，避免后期重构的痛苦。
扩展阅读资源
Microsoft Docs: Globalization and localization
ASP.NET Core Localization on GitHub
ICU MessageFormat 语法参考
通过遵循本指南，您将能够构建真正支持全球用户的ASP.NET应用程序，为您的业务国际化奠定坚实的技术基础。