Dosaic.Extensions.Localization.Generator 1.2.41

Dosaic.Extensions.Localization.Generator

Dosaic.Extensions.Localization.Generator is a Roslyn IIncrementalGenerator that runs at compile time to discover all types and members annotated with [LocalizedName] and emit a static EntityLabels lookup class into the consuming project. It can also write per-culture JSON translation files to disk during the build.

Installation

dotnet add package Dosaic.Extensions.Localization.Abstractions
dotnet add package Dosaic.Extensions.Localization.Generator

Or as PackageReference entries in your .csproj:

<PackageReference Include="Dosaic.Extensions.Localization.Abstractions" Version="" />
<PackageReference Include="Dosaic.Extensions.Localization.Generator" Version=""
                  OutputItemType="Analyzer" ReferenceOutputAssembly="false" />

Features

• Incremental generation — uses IIncrementalGenerator; only reruns when annotated nodes change
• Multiple targets — handles [LocalizedName] on classes, enums, enum members, properties, and fields
• Locale-typed API — all culture parameters use Locale.En / Locale.De instead of magic strings
• Configurable default culture — EntityLabels.DefaultCulture can be set at runtime; defaults to Locale.En
• Fallback — returns the member or type name when no translation is registered for the requested culture
• JSON export — writes a translation JSON file per culture when MSBuild properties are configured

Generated output

Given:

[LocalizedName(en: "Order", de: "Bestellung")]
public class Order
{
    [LocalizedName(en: "Order Number", de: "Bestellnummer")]
    public string OrderNumber { get; set; }
}

[LocalizedName(en: "Order Status", de: "Bestellstatus")]
public enum OrderStatus
{
    [LocalizedName(en: "Active", de: "Aktiv")]
    Active
}

The generator emits EntityLabels.g.cs:

// <auto-generated/>
namespace Dosaic.Extensions.Localization
{
    public static partial class EntityLabels
    {
        // Labels keyed by "TypeName" (type-level) or "TypeName.MemberName" (member-level)
        private static readonly Dictionary<string, Dictionary<string, string>> Labels = ...;

        public static Locale DefaultCulture = Locale.En;

        // Raw key lookup
        public static string Get(string key);
        public static string Get(string key, Locale culture);

        // Type-level (class / enum)
        public static string Get<T>();
        public static string Get<T>(Locale culture);

        // Enum member by value
        public static string Get(System.Enum value);
        public static string Get(System.Enum value, Locale culture);

        // Property / field by expression
        public static string Get<T>(Expression<Func<T, object>> memberSelector);
        public static string Get<T>(Expression<Func<T, object>> memberSelector, Locale culture);
    }
}

Key format

JSON export

The generator can write translation files to disk on every build. Declare the output paths as MSBuild properties and expose them to the generator via CompilerVisibleProperty:

<PropertyGroup>
  <LocalizationJsonDeOutputPath>$(MSBuildProjectDirectory)\localization.de.json</LocalizationJsonDeOutputPath>
  <LocalizationJsonEnOutputPath>$(MSBuildProjectDirectory)\localization.en.json</LocalizationJsonEnOutputPath>
</PropertyGroup>

<ItemGroup>
  <CompilerVisibleProperty Include="LocalizationJsonDeOutputPath" />
  <CompilerVisibleProperty Include="LocalizationJsonEnOutputPath" />
</ItemGroup>

Either property can be omitted to skip that culture. The file is written on every compilation that touches an annotated node.

Output format

Entries are grouped by type name. Type-level labels use the "$" key within their group; member labels use the member name.

{
  "Order": {
    "$": "Bestellung",
    "OrderNumber": "Bestellnummer"
  },
  "OrderStatus": {
    "$": "Bestellstatus",
    "Active": "Aktiv",
    "Cancelled": "Storniert"
  }
}

How it works

1. Attribute discovery — ForAttributeWithMetadataName matches [Dosaic.Extensions.Localization.LocalizedNameAttribute] on PropertyDeclarationSyntax, FieldDeclarationSyntax, EnumMemberDeclarationSyntax, ClassDeclarationSyntax, RecordDeclarationSyntax, StructDeclarationSyntax, and EnumDeclarationSyntax
2. Symbol extraction — IPropertySymbol and IFieldSymbol produce member-level entries keyed "TypeName.MemberName"; INamedTypeSymbol produces type-level entries keyed "TypeName"
3. Source emission — RegisterSourceOutput collects all results and emits EntityLabels.g.cs into the compilation
4. JSON writing — reads LocalizationJsonDeOutputPath / LocalizationJsonEnOutputPath from AnalyzerConfigOptionsProvider.GlobalOptions and writes grouped JSON files to disk if paths are set