{"id":30141781,"url":"https://github.com/dotnet9/lang.avalonia","last_synced_at":"2025-08-11T05:18:30.901Z","repository":{"id":308831230,"uuid":"1033869089","full_name":"dotnet9/Lang.Avalonia","owner":"dotnet9","description":"Avalonia;AvaloniaUI;Translation","archived":false,"fork":false,"pushed_at":"2025-08-08T06:02:59.000Z","size":76,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-08T07:13:52.975Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dotnet9.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-07T13:24:07.000Z","updated_at":"2025-08-08T06:03:02.000Z","dependencies_parsed_at":"2025-08-08T07:24:30.885Z","dependency_job_id":null,"html_url":"https://github.com/dotnet9/Lang.Avalonia","commit_stats":null,"previous_names":["dotnet9/lang.avalonia"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dotnet9/Lang.Avalonia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet9%2FLang.Avalonia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet9%2FLang.Avalonia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet9%2FLang.Avalonia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet9%2FLang.Avalonia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dotnet9","download_url":"https://codeload.github.com/dotnet9/Lang.Avalonia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dotnet9%2FLang.Avalonia/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269833310,"owners_count":24482423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-11T05:18:30.210Z","updated_at":"2025-08-11T05:18:30.888Z","avatar_url":"https://github.com/dotnet9.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lang.Avalonia\n\n## 引言：为什么需要Lang.Avalonia？\n\n在跨平台UI开发中，多语言支持是提升用户体验的核心需求之一。Avalonia作为一款强大的跨平台UI框架，虽具备灵活的扩展性，但原生多语言方案在格式支持、开发效率和模块化集成上存在局限。  \n\n**Lang.Avalonia** 应运而生——这是一款专为Avalonia框架设计的多语言管理库，通过插件化架构重构了多语言支持逻辑，不仅兼容传统Resx资源文件，还新增XML和JSON格式支持，同时提供类型安全的资源引用、动态语言切换等能力，让多语言开发更简单、更高效。\n\n\n## 核心特性：为什么选择Lang.Avalonia？\n- **多格式兼容**：支持Resx（传统.NET资源格式）、XML、JSON三种语言文件格式，满足不同项目的格式偏好。\n- **类型安全引用**：通过T4模板自动生成C#常量类，避免硬编码字符串Key，编译期即可检测资源引用错误。\n- **前后台无缝集成**：提供XAML标记扩展（`{c:I18n}`）和C# API双端支持，前台UI绑定与后台逻辑调用同样便捷。\n- **动态语言切换**：支持运行时切换语言文化，无需重启应用即可实时更新界面文本。\n- **模块化管理**：支持按项目模块拆分语言文件（如主模块、开发模块），适配大型项目的多团队协作。\n- **轻量易集成**：插件化设计，仅需安装对应格式的NuGet包，几行代码即可完成初始化。\n\n\n## 快速开始：安装与基础配置\n\n### 第一步：安装NuGet包\n根据项目使用的语言文件格式，选择对应的安装命令：\n\n| 语言文件格式 | 安装命令 | 适用场景 |\n|--------------|----------|----------|\n| Resx | `Install-Package Lang.Avalonia.Resx` | 习惯传统.NET Resx资源文件的项目 |\n| XML | `Install-Package Lang.Avalonia.Xml` | 偏好轻量XML格式、需手动编辑的项目 |\n| JSON | `Install-Package Lang.Avalonia.Json` | 现代前端风格项目、需跨端共享语言文件的场景 |\n\n\n### 第二步：创建语言文件\n按规范创建语言文件，建议统一放在项目根目录的`i18n`文件夹中，文件命名需包含文化标识（如`zh-CN`代表简体中文，`en-US`代表美式英语）。\n\n#### Resx格式\nResx文件需以基础文件名（如`Resources.resx`）+ 文化标识（可选）命名，基础文件默认为 fallback 语言，具体参考示例项目：\n```\ni18n/Resources.resx          // 默认语言（如英语）\ni18n/Resources.zh-CN.resx    // 简体中文\ni18n/Resources.zh-Hant.resx  // 繁体中文\ni18n/Resources.ja-JP.resx    // 日语\n```\n![](https://img1.dotnet9.com/2025/08/0201.png)\n\n#### XML格式\n\nXML文件直接以文化标识命名，每个文件独立存储对应语言的资源：\n```\ni18n/en-US.xml    // 美式英语\ni18n/zh-CN.xml    // 简体中文\ni18n/zh-Hant.xml  // 繁体中文\ni18n/ja-JP.xml    // 日语\n```\n![](https://img1.dotnet9.com/2025/08/0203.png)\n\n#### JSON格式示例\nJSON文件同样以文化标识命名，采用键值对结构存储资源：\n```\ni18n/en-US.json    // 美式英语\ni18n/zh-CN.json    // 简体中文\ni18n/zh-Hant.json  // 繁体中文\ni18n/ja-JP.json    // 日语\n```\n![](https://img1.dotnet9.com/2025/08/0202.png)\n\n\n### 第三步：生成类型安全的资源常量（T4模板）\n为避免硬编码资源Key（如直接写字符串`\"SettingView.Title\"`），通过T4模板自动生成C#常量类，支持编译期校验。\n\n#### 操作步骤：\n1. 从Lang.Avalonia.XX.Demo示例项目中复制对应格式的T4模板（Resx/XML/JSON模板不同），放入项目的`i18n`文件夹（需自行创建）。\n2. 模板会自动扫描`i18n`文件夹的语言文件，生成语言资源的常量类\n3. 当语言文件新增/修改Key后，打开T4模板按Ctrl + S可重新生成。\n\n![](https://img1.dotnet9.com/2025/08/0204.png)\n\n\n## 实战使用：前后台集成指南\n\n### 初始化多语言管理器\n在应用启动时（推荐在`App.axaml.cs`的`Initialize`方法中）初始化多语言管理器，预加载语言资源：\n\n```csharp\n// 引入命名空间\nusing Lang.Avalonia;\nusing Lang.Avalonia.Resx; // 对应格式的命名空间（Resx/Xml/Json）\nusing System.Globalization;\n\npublic override void Initialize()\n{\n    base.Initialize();\n    // 初始化Resx格式（其他格式替换为XmlLangPlugin/JsonLangPlugin）\n    I18nManager.Instance.Register(\n        plugin: new ResxLangPlugin(),  // 格式插件\n        defaultCulture: new CultureInfo(\"zh-CN\"),  // 默认语言\n        error: out var error  // 错误信息（可选）\n    );\n    if (!string.IsNullOrEmpty(error))\n    {\n        // 处理初始化错误（如文件不存在）\n        Console.WriteLine($\"多语言初始化失败：{error}\");\n    }\n}\n```\n\n\n### 前台XAML绑定使用\n通过`{c:I18n}`标记扩展在AXAML中绑定资源，支持直接引用T4生成的常量类，还可指定特定语言：\n\n```xml\n\u003c!-- 引入命名空间 --\u003e\nxmlns:c=\"https://codewf.com\"  \u003c!-- Lang.Avalonia的标记扩展命名空间 --\u003e\nxmlns:mainLangs=\"clr-namespace:Localization.Main\"  \u003c!-- 主模块常量类 --\u003e\nxmlns:developModule=\"clr-namespace:Localization.DevelopModule\"  \u003c!-- 开发模块常量类 --\u003e\n\n\u003c!-- 绑定当前默认语言的资源 --\u003e\n\u003cSelectableTextBlock Text=\"{c:I18n {x:Static mainLangs:SettingView.Title}}\" /\u003e\n\n\u003c!-- 强制指定语言（如简体中文） --\u003e\n\u003cSelectableTextBlock \n    Text=\"{c:I18n {x:Static developModule:Title2SlugView.Title}, CultureName=zh-CN}\" \n/\u003e\n```\n\n\n### 后台C#逻辑使用\n通过`I18nManager.Instance.GetResource`方法在后台代码中获取资源，支持获取当前语言或指定语言的文本：\n\n```csharp\n// 引入生成的常量命名空间\nusing Localization.Main;\n\n// 获取当前默认语言的资源\nvar titleCurrent = I18nManager.Instance.GetResource(MainView.Title);\n\n// 获取指定语言的资源（简体中文）\nvar titleZhCN = I18nManager.Instance.GetResource(MainView.Title, \"zh-CN\");\n\n// 获取指定语言的资源（美式英语）\nvar titleEnUS = I18nManager.Instance.GetResource(MainView.Title, \"en-US\");\n```\n\n\n### 进阶技巧：动态切换语言\n运行时切换语言只需设置属性`I18nManager.Instance.Culture`，界面会自动更新：\n\n```csharp\n// 切换为英语\nI18nManager.Instance.Culture = new CultureInfo(\"en-US\");\n\n// 切换为日语\nI18nManager.Instance.Culture = new CultureInfo(\"ja-JP\");\n```\n\n\n## 注意事项与最佳实践\n1. **文化标识规范**：统一使用`zh-CN`（简体中文）、`en-US`（美式英语）等标准文化名称，避免混用`zh_CN`等非标准格式。\n2. **模块化拆分**：大型项目建议按功能模块拆分语言文件（如主模块、用户模块），T4模板会自动生成对应模块的常量类，避免Key冲突。\n3. **Fallback机制**：当指定语言的资源不存在时，会自动 fallback 到默认语言（初始化时指定的`defaultCulture`），建议保留默认语言文件作为兜底。\n4. **性能优化**：语言资源会在初始化时缓存，适合频繁切换语言的场景；若语言文件较大，可考虑异步加载（需结合Avalonia的异步初始化机制）。\n\n\n## 结语\nLang.Avalonia通过插件化设计、多格式支持和类型安全特性，大幅简化了Avalonia项目的多语言开发流程。无论是传统Resx用户，还是偏好XML/JSON的现代项目，都能快速集成并享受高效的多语言管理体验。\n\n若在使用中遇到问题或需要扩展新格式，可参考Lang.Avalonia的插件接口实现自定义语言插件，也欢迎参与项目贡献！\n\n仓库地址：https://github.com/dotnet9/Lang.Avalonia","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotnet9%2Flang.avalonia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdotnet9%2Flang.avalonia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdotnet9%2Flang.avalonia/lists"}