{"id":15059866,"url":"https://github.com/andrewkeepcoding/winui3localizer","last_synced_at":"2025-04-12T23:39:59.496Z","repository":{"id":65584433,"uuid":"594062888","full_name":"AndrewKeepCoding/WinUI3Localizer","owner":"AndrewKeepCoding","description":"The WinUI3Localizer is a NuGet package that helps you localize your WinUI 3 app.","archived":false,"fork":false,"pushed_at":"2025-03-30T13:29:22.000Z","size":955,"stargazers_count":103,"open_issues_count":11,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T23:39:37.442Z","etag":null,"topics":["localization","localizer","multilanguage","winappsdk","winui","winui3"],"latest_commit_sha":null,"homepage":"","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/AndrewKeepCoding.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2023-01-27T14:11:57.000Z","updated_at":"2025-04-10T10:35:04.000Z","dependencies_parsed_at":"2023-02-16T07:45:49.998Z","dependency_job_id":"b026d0a5-97f8-4889-897c-8f7804d3913c","html_url":"https://github.com/AndrewKeepCoding/WinUI3Localizer","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndrewKeepCoding%2FWinUI3Localizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndrewKeepCoding%2FWinUI3Localizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndrewKeepCoding%2FWinUI3Localizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndrewKeepCoding%2FWinUI3Localizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AndrewKeepCoding","download_url":"https://codeload.github.com/AndrewKeepCoding/WinUI3Localizer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647254,"owners_count":21139081,"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","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":["localization","localizer","multilanguage","winappsdk","winui","winui3"],"created_at":"2024-09-24T22:49:12.223Z","updated_at":"2025-04-12T23:39:59.454Z","avatar_url":"https://github.com/AndrewKeepCoding.png","language":"C#","readme":"# 🌏WinUI3Localizer\n\n**WinUI3Localizer** is a NuGet package that helps you localize your WinUI 3 app.\n\n- Switch languages **without app restarting**\n- You/users can **edit** localized strings even after deployment\n- You/users can **add** new languages even after deployment\n- Use standard **Resources.resw** (see [Microsoft docs](https://learn.microsoft.com/en-us/windows/uwp/app-resources/localize-strings-ui-manifest))\n\n## 🙌 Quick Start\n\n\u003e **Note**: This is a quick start guide. Check the sample app for details.\n\n### **Install WinUI3Localizer**\n\nInstall **WinUI3Localizer** from the NuGet Package Manager.\n\n### **Create localized strings**\n\nCreate a \"Strings\" folder in your app project and populate it with your string resources files for each language you need. For example, this is a basic structure for English (en-US), es-ES (Spanish) and Japanese (ja) resources files.\n\n- Strings\n  - en-US\n    - Resources.resw\n  - es-ES\n    - Resources.resw\n  - ja\n    - Resources.resw\n\nAdd this ItemGroup in the project file (\\*.csproj) of your app.\n\n```xml\n\u003c!-- Copy all \"Resources.resw\" files in the \"Strings\" folder to the output folder. --\u003e\n\u003cItemGroup\u003e\n  \u003cContent Include=\"Strings\\**\\*.resw\"\u003e\n    \u003cCopyToOutputDirectory\u003ePreserveNewest\u003c/CopyToOutputDirectory\u003e\n  \u003c/Content\u003e\n\u003c/ItemGroup\u003e\n```\n\n\u003e **Note**: The \"Strings\" folder can be anywhere as long the app can access it. Usually, aside the app executable for non-packaged apps, or in the \"LocalFolder\" for packaged-apps.\n\n### **Build WinUI3Localizer**\n\n- Non-packaged apps:\n\n  In App.xaml.cs, build **WinUI3Localizer** like this:\n\n  ```csharp\n  private async Task InitializeLocalizer()\n  {\n      // Initialize a \"Strings\" folder in the executables folder.\n      StringsFolderPath StringsFolderPath = Path.Combine(AppContext.BaseDirectory, \"Strings\");\n      StorageFolder stringsFolder = await StorageFolder.GetFolderFromPathAsync(StringsFolderPath);\n\n      ILocalizer localizer = await new LocalizerBuilder()\n          .AddStringResourcesFolderForLanguageDictionaries(StringsFolderPath)\n          .SetOptions(options =\u003e\n          {\n              options.DefaultLanguage = \"en-US\";\n          })\n          .Build();\n  }\n  ```\n\n- Packaged apps:\n\n  In App.xaml.cs, build **WinUI3Localizer** like this:\n\n  ```csharp\n  private async Task InitializeLocalizer()\n  {\n\n      // Initialize a \"Strings\" folder in the \"LocalFolder\" for the packaged app.\n      StorageFolder localFolder = ApplicationData.Current.LocalFolder;\n      StorageFolder stringsFolder = await localFolder.CreateFolderAsync(\n        \"Strings\",\n         CreationCollisionOption.OpenIfExists);\n\n      // Create string resources file from app resources if doesn't exists.\n      string resourceFileName = \"Resources.resw\";\n      await CreateStringResourceFileIfNotExists(stringsFolder, \"en-US\", resourceFileName);\n      await CreateStringResourceFileIfNotExists(stringsFolder, \"es-ES\", resourceFileName);\n      await CreateStringResourceFileIfNotExists(stringsFolder, \"ja\", resourceFileName);\n\n      ILocalizer localizer = await new LocalizerBuilder()\n          .AddStringResourcesFolderForLanguageDictionaries(stringsFolder.Path)\n          .SetOptions(options =\u003e\n          {\n              options.DefaultLanguage = \"en-US\";\n          })\n          .Build();\n  }\n\n  private static async Task CreateStringResourceFileIfNotExists(StorageFolder stringsFolder, string language, string resourceFileName)\n  {\n      StorageFolder languageFolder = await stringsFolder.CreateFolderAsync(\n          language,\n          CreationCollisionOption.OpenIfExists);\n\n      if (await languageFolder.TryGetItemAsync(resourceFileName) is null)\n      {\n          string resourceFilePath = Path.Combine(stringsFolder.Name, language, resourceFileName);\n          StorageFile resourceFile = await LoadStringResourcesFileFromAppResource(resourceFilePath);\n          _ = await resourceFile.CopyAsync(languageFolder);\n      }\n  }\n\n  private static async Task\u003cStorageFile\u003e LoadStringResourcesFileFromAppResource(string filePath)\n  {\n      Uri resourcesFileUri = new($\"ms-appx:///{filePath}\");\n      return await StorageFile.GetFileFromApplicationUriAsync(resourcesFileUri);\n  }\n  ```\n\n### **Localizing controls**\n\nThis is an example of how to localize the `Content` of a `Button`.\n\nFirst asign an `Uid` to the `Button`, then in each language resources file, add an item that corresponds to the `Uid`.\n\nYou can also have multiple string resources files. For example, besides the default **Resources.resw** file, you can have a **Messages.resw** for your messages file.\nTo just need to include `/\u003cresources-file-name\u003e/` before the string resource identifier.\n\n```xml\n\u003cPage\n    x:Class=\"WinUI3Localizer.SampleApp.TestPage\"\n    ...\n    xmlns:l=\"using:WinUI3Localizer\"\u003e\n    \u003cStackPanel\u003e\n        \u003cButton l:Uids.Uid=\"TestPage_Button\"\u003e\n            \u003cButton.Flyout\u003e\n                \u003cFlyout\u003e\n                    \u003cTextBlock l:Uids.Uid=\"/Messages/ButtonFlyoutMessage\" /\u003e\n                \u003c/Flyout\u003e\n            \u003c/Button.Flyout\u003e\n        \u003c/Button\u003e\n    \u003c/StackPanel\u003e\n\u003c/Page\u003e\n```\n\n- en-US\n\n  - Resources.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | TestPageButton.Content | Awesome! |\n\n  - Messages.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | ButtonFlyoutMessage.Text | This is an awesome message! |\n\n- es-ES:\n\n  - Resources.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | TestPageButton.Content | ¡Increíble! |\n\n  - Messages.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | ButtonFlyoutMessage.Text | ¡Esto es un mensaje increíble! |\n\n- ja:\n\n  - Resources.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | TestPageButton.Content | 素晴らしい！ |\n\n  - Messages.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | ButtonFlyoutMessage.Text | これは素晴らしいメッセージです！ |\n\n### **Getting localized strings**\n\nIf we need to localize strings in code-behind or in ViewModels, we can use the `GetLocalizedString()` method.\n\n```csharp\nList\u003cstring\u003e colors = new()\n{\n    \"Red\",\n    \"Green\",\n    \"Blue\",\n};\n\nILocalizer localizer = Localizer.Get();\nList\u003cstring\u003e localizedColors = colors\n    .Select(x =\u003e localizer.GetLocalizedString(x))\n    .ToList();\n```\n\nIn this case, we just use the `Uid` as `Name`.\n\n- en-US\n\n  - Resources.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | Red | Red |\n    | Green | Green |\n    | Blue | Blue |\n\n- es-ES:\n\n  - Resources.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | Red | Rojo |\n    | Green | Verde |\n    | Blue | Azul |\n\n- ja:\n\n  - Resources.resw\n\n    | Name | Value |\n    | ---- | ----- |\n    | Red | 赤 |\n    | Green | 緑 |\n    | Blue | 青 |\n### **Minimal example**\nRefer to [TemplateStudioWinUI3LocalizerSampleApp\n](https://github.com/AndrewKeepCoding/TemplateStudioWinUI3LocalizerSampleApp)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewkeepcoding%2Fwinui3localizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewkeepcoding%2Fwinui3localizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewkeepcoding%2Fwinui3localizer/lists"}