Base Setup

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation.Test/LocalisationTestConstants.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System;
+using System.Collections.Generic;
+using PG.StarWarsGame.Components.Localisation.Languages.BuiltIn;
+
+namespace PG.StarWarsGame.Components.Localisation.Test;
+
+public sealed class LocalisationTestConstants
+{
+    public static readonly IList<Type> REGISTERED_LANGUAGE_DEFINITIONS = new List<Type>
+    {
+        //[gruenwaldlu, 2021-04-18-12:02:51+2]: All officially supported languages are listed below. 
+        typeof(ChineseAlamoLanguageDefinition), typeof(EnglishAlamoLanguageDefinition),
+        typeof(FrenchAlamoLanguageDefinition), typeof(GermanAlamoLanguageDefinition),
+        typeof(ItalianAlamoLanguageDefinition), typeof(JapaneseAlamoLanguageDefinition),
+        typeof(KoreanAlamoLanguageDefinition), typeof(PolishAlamoLanguageDefinition),
+        typeof(RussianAlamoLanguageDefinition), typeof(SpanishAlamoLanguageDefinition),
+        typeof(ThaiAlamoLanguageDefinition)
+    };
+
+    public static readonly Type DEFAULT_LANGUAGE = typeof(EnglishAlamoLanguageDefinition);
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation.Test/PG.StarWarsGame.Components.Localisation.Test.csproj

@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+	<PropertyGroup>
+		<IsPackable>false</IsPackable>
+		<TargetFrameworks>net8.0</TargetFrameworks>
+		<TargetFrameworks Condition="!$([MSBuild]::IsOsUnixLike())">$(TargetFrameworks);net48</TargetFrameworks>
+	</PropertyGroup>
+	<ItemGroup>
+		<PackageReference Include="coverlet.msbuild" Version="6.0.2">
+			<PrivateAssets>all</PrivateAssets>
+			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+		</PackageReference>
+		<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
+		<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.1" />
+		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.10.0" />
+		<PackageReference Include="xunit" Version="2.8.1" />
+		<PackageReference Include="xunit.runner.visualstudio" Version="2.8.1">
+			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+			<PrivateAssets>all</PrivateAssets>
+		</PackageReference>
+		<PackageReference Include="coverlet.collector" Version="6.0.2">
+			<PrivateAssets>all</PrivateAssets>
+			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+		</PackageReference>
+		<PackageReference Include="System.IO.Abstractions" Version="21.0.2" />
+		<PackageReference Include="Testably.Abstractions.Testing" Version="3.2.1" />
+	</ItemGroup>
+	<ItemGroup>
+		<ProjectReference Include="..\..\PG.Commons\PG.Commons.Test\PG.Commons.Test.csproj" />
+		<ProjectReference Include="..\..\PG.Testing\PG.Testing.csproj" />
+		<ProjectReference Include="..\PG.StarWarsGame.Components.Localisation\PG.StarWarsGame.Components.Localisation.csproj" />
+	</ItemGroup>
+</Project>

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Attributes/DefaultLanguageAttribute.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System;
+
+namespace PG.StarWarsGame.Components.Localisation.Attributes;
+
+/// <summary>
+///     Marks the default (fallback) language.
+/// </summary>
+public class DefaultLanguageAttribute : Attribute
+{
+    /// <summary>
+    ///     .ctor
+    /// </summary>
+    public DefaultLanguageAttribute()
+    {
+        IsDefaultLanguage = true;
+    }
+
+    /// <summary>
+    ///     .ctor
+    /// </summary>
+    /// <param name="isDefaultLanguage"></param>
+    public DefaultLanguageAttribute(bool isDefaultLanguage)
+    {
+        IsDefaultLanguage = isDefaultLanguage;
+    }
+
+    /// <summary>
+    ///     Returns true for the default language.
+    /// </summary>
+    public bool IsDefaultLanguage { get; }
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Attributes/OfficiallySupportedLanguageAttribute.cs

@@ -0,0 +1,37 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+
+namespace PG.StarWarsGame.Components.Localisation.Attributes;
+
+/// <summary>
+///     Marks a language as officially supported.
+/// </summary>
+[AttributeUsage(AttributeTargets.Class, Inherited = false)]
+[ExcludeFromCodeCoverage]
+public sealed class OfficiallySupportedLanguageAttribute : Attribute
+{
+    /// <summary>
+    ///     .ctor
+    /// </summary>
+    public OfficiallySupportedLanguageAttribute()
+    {
+        IsOfficiallySupported = true;
+    }
+
+    /// <summary>
+    ///     .ctor
+    /// </summary>
+    /// <param name="isOfficiallySupported"></param>
+    public OfficiallySupportedLanguageAttribute(bool isOfficiallySupported)
+    {
+        IsOfficiallySupported = isOfficiallySupported;
+    }
+
+    /// <summary>
+    ///     Returns true if the language is officially supported.
+    /// </summary>
+    public bool IsOfficiallySupported { get; }
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Languages/AlamoLanguageDefinitionBase.cs

@@ -0,0 +1,100 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System;
+using System.Globalization;
+
+namespace PG.StarWarsGame.Components.Localisation.Languages;
+
+/// <summary>
+///     Abstract language definition
+/// </summary>
+public abstract class AlamoLanguageDefinitionBase : IAlamoLanguageDefinition, IComparable
+{
+    /// <summary>
+    ///     A string that is being used to identify the language of the *.DAT file, e.g. a language identifier
+    ///     "english" would produce the file "mastertextfile_english.dat"
+    /// </summary>
+    protected abstract string ConfiguredLanguageIdentifier { get; }
+
+    /// <summary>
+    ///     The .NET Culture that best describes the language. This culture can be used for spell checking,
+    ///     auto-translation between languages, etc.
+    /// </summary>
+    protected abstract CultureInfo ConfiguredCulture { get; }
+
+    /// <inheritdoc />
+    public string LanguageIdentifier => ConfiguredLanguageIdentifier;
+
+    /// <inheritdoc />
+    public CultureInfo Culture => ConfiguredCulture;
+
+    /// <inheritdoc />
+    public int CompareTo(object obj)
+    {
+        if (obj is not IAlamoLanguageDefinition other)
+            throw new ArgumentException(
+                $"The type of {obj.GetType()} is not assignable to {typeof(IAlamoLanguageDefinition)}. The two objects cannot be compared.");
+
+        return CompareToInternal(other);
+    }
+
+    /// <summary>
+    ///     Compares the current instance with another object of the same type and returns an integer that indicates
+    ///     whether the current instance precedes, follows, or occurs in the same position in the sort order as the
+    ///     other object.
+    /// </summary>
+    /// <remarks>
+    ///     The <see cref="IAlamoLanguageDefinition" /> specific override differs in its sort order in such a way,
+    ///     that all elements are ordered by their <see cref="CultureInfo.TwoLetterISOLanguageName" />t.
+    /// </remarks>
+    /// <param name="other"></param>
+    /// <returns></returns>
+    protected virtual int CompareToInternal(IAlamoLanguageDefinition other)
+    {
+        return string.Compare(Culture.TwoLetterISOLanguageName, other.Culture.TwoLetterISOLanguageName,
+            StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    ///     Determines whether the specified object is equal to the current object.
+    /// </summary>
+    /// <param name="other"></param>
+    /// <returns></returns>
+    protected virtual bool EqualsInternal(IAlamoLanguageDefinition other)
+    {
+        return CompareTo(other) == 0;
+    }
+
+    /// <summary>
+    ///     Serves as the default hash function.
+    /// </summary>
+    /// <remarks>
+    ///     The default implementation does intentionally create hash conflicts between identical language definitions,
+    ///     e.g. using the same <see cref="LanguageIdentifier" /> and <see cref="Culture" /> for two different derived classes.
+    /// </remarks>
+    /// <returns></returns>
+    protected virtual int GetHashCodeInternal()
+    {
+        unchecked
+        {
+            return (ConfiguredLanguageIdentifier.GetHashCode() * 397) ^ Culture.GetHashCode();
+        }
+    }
+
+    /// <inheritdoc />
+    public override bool Equals(object? obj)
+    {
+        if (obj is null) return false;
+
+        if (ReferenceEquals(this, obj)) return true;
+
+        return obj is IAlamoLanguageDefinition alamoLanguageDefinition && EqualsInternal(alamoLanguageDefinition);
+    }
+
+    /// <inheritdoc />
+    public override int GetHashCode()
+    {
+        return GetHashCodeInternal();
+    }
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Languages/BuiltIn/ChineseAlamoLanguageDefinition.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+using PG.StarWarsGame.Components.Localisation.Attributes;
+
+namespace PG.StarWarsGame.Components.Localisation.Languages.BuiltIn;
+
+/// <summary>
+///     The language definition for the Chinese language.
+/// </summary>
+/// <remarks>
+///     Officially supported by the Alamo Engine.
+/// </remarks>
+[ExcludeFromCodeCoverage]
+[OfficiallySupportedLanguage]
+public sealed class ChineseAlamoLanguageDefinition : AlamoLanguageDefinitionBase
+{
+    /// <inheritdoc />
+    protected override string ConfiguredLanguageIdentifier => "CHINESE";
+
+    /// <inheritdoc />
+    protected override CultureInfo ConfiguredCulture => CultureInfo.GetCultureInfo("zh-CN");
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Languages/BuiltIn/EnglishAlamoLanguageDefinition.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+using PG.StarWarsGame.Components.Localisation.Attributes;
+
+namespace PG.StarWarsGame.Components.Localisation.Languages.BuiltIn;
+
+/// <summary>
+///     The language definition for the English (US) language.
+/// </summary>
+/// <remarks>
+///     Officially supported by the Alamo Engine.<br />
+///     This language is the default game language and development language of all Alamo Engine games.
+/// </remarks>
+[ExcludeFromCodeCoverage]
+[DefaultLanguage]
+[OfficiallySupportedLanguage]
+public sealed class EnglishAlamoLanguageDefinition : AlamoLanguageDefinitionBase
+{
+    /// <inheritdoc />
+    protected override string ConfiguredLanguageIdentifier => "ENGLISH";
+
+    /// <inheritdoc />
+    protected override CultureInfo ConfiguredCulture => CultureInfo.GetCultureInfo("en-US");
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Languages/BuiltIn/FrenchAlamoLanguageDefinition.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+using PG.StarWarsGame.Components.Localisation.Attributes;
+
+namespace PG.StarWarsGame.Components.Localisation.Languages.BuiltIn;
+
+/// <summary>
+///     The language definition for the French language.
+/// </summary>
+/// <remarks>
+///     Officially supported by the Alamo Engine.
+/// </remarks>
+[ExcludeFromCodeCoverage]
+[OfficiallySupportedLanguage]
+public sealed class FrenchAlamoLanguageDefinition : AlamoLanguageDefinitionBase
+{
+    /// <inheritdoc />
+    protected override string ConfiguredLanguageIdentifier => "FRENCH";
+
+    /// <inheritdoc />
+    protected override CultureInfo ConfiguredCulture => CultureInfo.GetCultureInfo("fr-FR");
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Languages/BuiltIn/GermanAlamoLanguageDefinition.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+using PG.StarWarsGame.Components.Localisation.Attributes;
+
+namespace PG.StarWarsGame.Components.Localisation.Languages.BuiltIn;
+
+/// <summary>
+///     The language definition for the German language.
+/// </summary>
+/// <remarks>
+///     Officially supported by the Alamo Engine.
+/// </remarks>
+[ExcludeFromCodeCoverage]
+[OfficiallySupportedLanguage]
+public sealed class GermanAlamoLanguageDefinition : AlamoLanguageDefinitionBase
+{
+    /// <inheritdoc />
+    protected override string ConfiguredLanguageIdentifier => "GERMAN";
+
+    /// <inheritdoc />
+    protected override CultureInfo ConfiguredCulture => CultureInfo.GetCultureInfo("de-DE");
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Languages/BuiltIn/ItalianAlamoLanguageDefinition.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+using PG.StarWarsGame.Components.Localisation.Attributes;
+
+namespace PG.StarWarsGame.Components.Localisation.Languages.BuiltIn;
+
+/// <summary>
+///     The language definition for the Italian language.
+/// </summary>
+/// <remarks>
+///     Officially supported by the Alamo Engine.
+/// </remarks>
+[ExcludeFromCodeCoverage]
+[OfficiallySupportedLanguage]
+public sealed class ItalianAlamoLanguageDefinition : AlamoLanguageDefinitionBase
+{
+    /// <inheritdoc />
+    protected override string ConfiguredLanguageIdentifier => "ITALIAN";
+
+    /// <inheritdoc />
+    protected override CultureInfo ConfiguredCulture => CultureInfo.GetCultureInfo("it-IT");
+}

PG.StarWarsGame.Components.Localisation/PG.StarWarsGame.Components.Localisation/Languages/BuiltIn/JapaneseAlamoLanguageDefinition.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Alamo Engine Tools and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for details.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+using PG.StarWarsGame.Components.Localisation.Attributes;
+
+namespace PG.StarWarsGame.Components.Localisation.Languages.BuiltIn;
+
+/// <summary>
+///     The language definition for the Japanese language.
+/// </summary>
+/// <remarks>
+///     Officially supported by the Alamo Engine.
+/// </remarks>
+[ExcludeFromCodeCoverage]
+[OfficiallySupportedLanguage]
+public sealed class JapaneseAlamoLanguageDefinition : AlamoLanguageDefinitionBase
+{
+    /// <inheritdoc />
+    protected override string ConfiguredLanguageIdentifier => "JAPANESE";
+
+    /// <inheritdoc />
+    protected override CultureInfo ConfiguredCulture => CultureInfo.GetCultureInfo("ja");
+}