feat(localization): add resource-based localization foundation

GenHub/Directory.Packages.props

@@ -13,6 +13,7 @@
     <PackageVersion Include="Avalonia.Fonts.Inter" Version="11.2.7" />
     <PackageVersion Include="Avalonia.Controls.DataGrid" Version="11.2.7" />
     <PackageVersion Include="Avalonia.Diagnostics" Version="11.2.7" />
+    <PackageVersion Include="Avalonia.Headless.XUnit" Version="11.2.7" />
     <PackageVersion Include="CommunityToolkit.Mvvm" Version="8.2.1" />
     <PackageVersion Include="Markdig" Version="0.44.0" />
     <PackageVersion Include="Markdown.Avalonia" Version="11.0.2" />

GenHub/GenHub.Core/Constants/LocalizationConstants.cs

@@ -0,0 +1,32 @@
+namespace GenHub.Core.Constants;
+
+/// <summary>
+/// Constants used by the application localization infrastructure.
+/// </summary>
+public static class LocalizationConstants
+{
+    /// <summary>
+    /// The neutral culture embedded in the main application assembly.
+    /// </summary>
+    public const string DefaultCultureName = "en";
+
+    /// <summary>
+    /// The property name used to notify bindings that all indexer values changed.
+    /// </summary>
+    public const string IndexerPropertyName = "Item";
+
+    /// <summary>
+    /// The application resource key used to expose the localization service to XAML.
+    /// </summary>
+    public const string ResourceServiceKey = "LocalizationService";
+
+    /// <summary>
+    /// The fully qualified base name of the application's string resources.
+    /// </summary>
+    public const string StringResourceBaseName = "GenHub.Resources.Localization.Strings";
+
+    /// <summary>
+    /// The suffix used by .NET satellite resource assemblies.
+    /// </summary>
+    public const string SatelliteAssemblySuffix = ".resources.dll";
+}

GenHub/GenHub.Core/Interfaces/Common/ILocalizationService.cs

@@ -0,0 +1,44 @@
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Globalization;
+using GenHub.Core.Models.Results;
+
+namespace GenHub.Core.Interfaces.Common;
+
+/// <summary>
+/// Provides localized application strings and runtime culture switching.
+/// </summary>
+public interface ILocalizationService : INotifyPropertyChanged
+{
+    /// <summary>
+    /// Gets the cultures backed by the neutral resource or a deployed satellite assembly.
+    /// </summary>
+    IReadOnlyList<CultureInfo> AvailableCultures { get; }
+
+    /// <summary>
+    /// Gets the culture used for resource lookup and formatting performed by <see cref="GetString"/>.
+    /// </summary>
+    CultureInfo CurrentCulture { get; }
+
+    /// <summary>
+    /// Gets a localized string by resource key.
+    /// </summary>
+    /// <param name="key">The resource key to resolve.</param>
+    /// <returns>The localized value, its English fallback, or the key when no resource exists.</returns>
+    string this[string key] { get; }
+
+    /// <summary>
+    /// Gets and optionally formats a localized string.
+    /// </summary>
+    /// <param name="key">The resource key to resolve.</param>
+    /// <param name="arguments">Optional format arguments.</param>
+    /// <returns>The localized value, its English fallback, or the key when no resource exists.</returns>
+    string GetString(string key, params object?[] arguments);
+
+    /// <summary>
+    /// Changes the active culture when it has a deployed translation.
+    /// </summary>
+    /// <param name="culture">The culture to activate.</param>
+    /// <returns>A result indicating whether the requested culture was available and applied.</returns>
+    OperationResult SetCulture(CultureInfo culture);
+}

GenHub/GenHub.Tests/GenHub.Tests.Core/App/AppLifecycleTests.cs

@@ -1,3 +1,7 @@
+using Avalonia.Data;
+using Avalonia.Headless.XUnit;
+using GenHub.Common.Markup;
+using GenHub.Core.Constants;
 using GenHub.Core.Interfaces.Common;
 using GenHub.Core.Interfaces.GameProfiles;
 using Microsoft.Extensions.DependencyInjection;
@@ -48,10 +52,12 @@ public void App_Constructor_WithValidServices_DoesNotThrow()
         var services = new ServiceCollection();
         var mockUserSettingsService = new Mock<IUserSettingsService>();
         var mockConfigurationProvider = new Mock<IConfigurationProviderService>();
+        var mockLocalizationService = new Mock<ILocalizationService>();
         var mockProfileLauncherFacade = new Mock<IProfileLauncherFacade>();
 
         services.AddSingleton(typeof(IUserSettingsService), mockUserSettingsService.Object);
         services.AddSingleton(typeof(IConfigurationProviderService), mockConfigurationProvider.Object);
+        services.AddSingleton(typeof(ILocalizationService), mockLocalizationService.Object);
         services.AddSingleton(typeof(IProfileLauncherFacade), mockProfileLauncherFacade.Object);
 
         var serviceProvider = services.BuildServiceProvider();
@@ -61,4 +67,20 @@ public void App_Constructor_WithValidServices_DoesNotThrow()
         var app = Activator.CreateInstance(appType, serviceProvider);
         Assert.NotNull(app);
     }
+
+    /// <summary>
+    /// Verifies that application XAML loading exposes localization to markup extensions afterward.
+    /// </summary>
+    [AvaloniaFact]
+    public void App_Initialize_ExposesLocalizationServiceToMarkupExtensions()
+    {
+        var app = Assert.IsType<global::GenHub.App>(Avalonia.Application.Current);
+        Assert.Same(
+            TestAppBuilder.LocalizationService,
+            app.Resources[LocalizationConstants.ResourceServiceKey]);
+
+        var extension = new LocalizeExtension("App.Name");
+        var binding = Assert.IsType<Binding>(extension.ProvideValue(Mock.Of<IServiceProvider>()));
+        Assert.Same(TestAppBuilder.LocalizationService, binding.Source);
+    }
 }

GenHub/GenHub.Tests/GenHub.Tests.Core/App/TestAppBuilder.cs

@@ -0,0 +1,44 @@
+using Avalonia;
+using Avalonia.Headless;
+using Avalonia.Headless.XUnit;
+using GenHub.Core.Interfaces.Common;
+using GenHub.Core.Interfaces.GameProfiles;
+using Microsoft.Extensions.DependencyInjection;
+using Moq;
+
+[assembly: AvaloniaTestApplication(typeof(GenHub.Tests.Core.App.TestAppBuilder))]
+
+namespace GenHub.Tests.Core.App;
+
+/// <summary>
+/// Configures the GenHub application for cross-platform headless lifecycle tests.
+/// </summary>
+internal static class TestAppBuilder
+{
+    private static readonly Mock<ILocalizationService> LocalizationServiceMock = new();
+    private static readonly IServiceProvider ServiceProvider = CreateServiceProvider();
+
+    /// <summary>
+    /// Gets the localization service registered in the headless application.
+    /// </summary>
+    internal static ILocalizationService LocalizationService => LocalizationServiceMock.Object;
+
+    /// <summary>
+    /// Creates the Avalonia application builder used by headless tests.
+    /// </summary>
+    /// <returns>The configured application builder.</returns>
+    public static AppBuilder BuildAvaloniaApp()
+        => AppBuilder.Configure(() => new global::GenHub.App(ServiceProvider))
+            .UseHeadless(new AvaloniaHeadlessPlatformOptions());
+
+    private static IServiceProvider CreateServiceProvider()
+    {
+        var services = new ServiceCollection();
+        services.AddSingleton(Mock.Of<IUserSettingsService>());
+        services.AddSingleton(Mock.Of<IConfigurationProviderService>());
+        services.AddSingleton(LocalizationService);
+        services.AddSingleton(Mock.Of<IProfileLauncherFacade>());
+
+        return services.BuildServiceProvider();
+    }
+}

GenHub/GenHub.Tests/GenHub.Tests.Core/Collections/LocalizationCultureCollection.cs

@@ -0,0 +1,13 @@
+namespace GenHub.Tests.Core.Collections;
+
+/// <summary>
+/// Prevents culture-mutating localization tests from running beside unrelated tests.
+/// </summary>
+[CollectionDefinition(Name, DisableParallelization = true)]
+public sealed class LocalizationCultureCollection
+{
+    /// <summary>
+    /// The collection name used by culture-mutating tests.
+    /// </summary>
+    public const string Name = "Localization culture";
+}