LocalizationManager.JsonLocalization.Generator 0.7.11

LocalizationManager.JsonLocalization.Generator

A C# source generator that creates strongly-typed accessors for JSON localization resources. Get compile-time safety, IntelliSense, and refactoring support for your localized strings.

Part of the LRM (Localization Resource Manager) ecosystem.

Why Use a Source Generator?

Features

• Compile-Time Validation - Typos in resource keys are caught at build time
• Full IntelliSense - Autocomplete for all resource keys in your IDE
• Nested Classes - Hierarchical keys become nested static classes
• Pluralization Methods - Plural keys generate methods with count parameter
• Format String Support - Keys with placeholders generate parameterized methods
• Refactoring Support - Rename keys across your entire codebase
• Works with Runtime Package - Uses LocalizationManager.JsonLocalization under the hood

Installation

dotnet add package LocalizationManager.JsonLocalization
dotnet add package LocalizationManager.JsonLocalization.Generator

Quick Start

Step 1: Create JSON Resources

Create localization files in your project:

MyApp/
├── Resources/
│   ├── strings.json      # Default language
│   ├── strings.fr.json   # French
│   └── strings.de.json   # German
└── MyApp.csproj

Resources/strings.json:

{
  "appTitle": "My Application",
  "welcome": "Welcome to {0}!",
  "buttons": {
    "save": "Save",
    "cancel": "Cancel"
  },
  "items": {
    "zero": "No items",
    "one": "One item",
    "other": "{0} items"
  }
}

Step 2: Configure Your Project

Add the following to your .csproj file:

<ItemGroup>
  
  <PackageReference Include="LocalizationManager.JsonLocalization" Version="*" />

  
  <PackageReference Include="LocalizationManager.JsonLocalization.Generator" Version="*"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false" />
</ItemGroup>


<ItemGroup>
  <AdditionalFiles Include="Resources/*.json" />
</ItemGroup>


<ItemGroup>
  <None Include="Resources/*.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

Step 3: Use Generated Code

using MyApp;

// Initialize with resources path (once at startup)
Strings.Initialize("./Resources");

// Access strings with full IntelliSense
Console.WriteLine(Strings.AppTitle);           // "My Application"
Console.WriteLine(Strings.Welcome("MyApp"));   // "Welcome to MyApp!"

// Nested keys become nested classes
Console.WriteLine(Strings.Buttons.Save);       // "Save"
Console.WriteLine(Strings.Buttons.Cancel);     // "Cancel"

// Plural keys become methods
Console.WriteLine(Strings.Items(0));           // "No items"
Console.WriteLine(Strings.Items(1));           // "One item"
Console.WriteLine(Strings.Items(5));           // "5 items"

// Change culture
Strings.Localizer.Culture = new CultureInfo("fr");
Console.WriteLine(Strings.AppTitle);           // "Mon Application"

Generated Code Structure

The generator analyzes your default JSON file and creates a static class hierarchy:

From this JSON:

{
  "appTitle": "My App",
  "welcome": "Hello, {0}!",
  "buttons": {
    "save": "Save",
    "cancel": "Cancel"
  },
  "messageCount": {
    "zero": "No messages",
    "one": "One message",
    "other": "{0} messages"
  }
}

Generates this code:

namespace MyApp;

public static partial class Strings
{
    public static JsonLocalizer Localizer { get; private set; } = null!;

    public static void Initialize(string resourcesPath)
    {
        Localizer = new JsonLocalizer(resourcesPath, "strings");
    }

    // Simple key → Property
    public static string AppTitle => Localizer["appTitle"];

    // Key with placeholder → Method
    public static string Welcome(object arg0) => Localizer["welcome", arg0];

    // Nested object → Nested class
    public static class Buttons
    {
        public static string Save => Localizer["buttons.save"];
        public static string Cancel => Localizer["buttons.cancel"];
    }

    // Plural key → Method with count
    public static string MessageCount(int count)
        => Localizer.Plural("messageCount", count);
}

JSON Format Requirements

Simple Keys

{
  "key": "Value"
}

→ Generates: Strings.Key property

Keys with Placeholders

{
  "greeting": "Hello, {0}! You have {1} messages."
}

→ Generates: Strings.Greeting(object arg0, object arg1) method

Nested Keys

{
  "errors": {
    "notFound": "Not found",
    "accessDenied": "Access denied"
  }
}

→ Generates: Strings.Errors.NotFound, Strings.Errors.AccessDenied

Plural Keys

Keys with zero, one, two, few, many, or other children are detected as plural:

{
  "items": {
    "zero": "No items",
    "one": "One item",
    "other": "{0} items"
  }
}

→ Generates: Strings.Items(int count) method

Complete .csproj Configuration

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    
    <PackageReference Include="LocalizationManager.JsonLocalization" Version="*" />

    
    <PackageReference Include="LocalizationManager.JsonLocalization.Generator" Version="*"
                      OutputItemType="Analyzer"
                      ReferenceOutputAssembly="false" />
  </ItemGroup>

  
  <ItemGroup>
    <AdditionalFiles Include="Resources/*.json" />
  </ItemGroup>

  
  <ItemGroup>
    <None Include="Resources/*.json" CopyToOutputDirectory="PreserveNewest" />
  </ItemGroup>

</Project>

Using with Embedded Resources

For single-file deployment, embed the JSON files and initialize differently:

<ItemGroup>
  <EmbeddedResource Include="Resources/strings.json">
    <LogicalName>MyApp.Resources.strings.json</LogicalName>
  </EmbeddedResource>
  <EmbeddedResource Include="Resources/strings.fr.json" WithCulture="false">
    <LogicalName>MyApp.Resources.strings.fr.json</LogicalName>
  </EmbeddedResource>
</ItemGroup>


<ItemGroup>
  <AdditionalFiles Include="Resources/*.json" />
</ItemGroup>

// Initialize with embedded resources
Strings.InitializeEmbedded(
    typeof(Program).Assembly,
    "MyApp.Resources");

Managing Resources with LRM Tools

Create and manage your JSON localization files using the LRM ecosystem:

LRM CLI

# Create a new JSON localization project with interactive wizard
lrm init -i

# Validate your resources
lrm validate --path ./Resources

# Translate missing values
lrm translate --provider google --target fr,de,es

# Find unused keys in your code
lrm scan --path ./src

VS Code Extension

Install the Localization Manager extension:

ext install nickprotop.localization-manager

Features:

• Visual resource tree with validation
• Add/edit/delete keys
• One-click translation
• Find unused keys
• Export/import resources

Workflow Example

1. Create project with wizard:

   lrm init -i
   # Choose JSON format, set languages, etc.
   

2. Add keys as you develop:

   • Use VS Code extension or lrm edit
   • Keys appear immediately in IntelliSense after rebuild

3. Validate before commit:

   lrm validate
   

4. Translate missing values:

   lrm translate --provider deepl --target fr,de
   

5. Find unused keys:

   lrm scan --path ./src
   

Troubleshooting

Generated Code Not Appearing

1. Check AdditionalFiles configuration:

   <AdditionalFiles Include="Resources/*.json" />
   

2. Rebuild the project:

   dotnet clean && dotnet build
   

3. Check for JSON syntax errors:

   lrm validate --path ./Resources
   

IntelliSense Not Working

1. Restart your IDE
2. Check that the generator package has OutputItemType="Analyzer"
3. Ensure you're referencing the correct namespace

Runtime "Key Not Found" Errors

1. Verify resources are copied to output:

   <None Include="Resources/*.json" CopyToOutputDirectory="PreserveNewest" />
   

2. Check the initialization path matches the output location

Build Errors After Renaming Keys

This is by design! The generator ensures compile-time safety. Update all usages of the renamed key.

Sample Project

See the complete working example:

ConsoleApp.SourceGenerator

Demonstrates:

• Basic setup and initialization
• Nested key access
• Pluralization
• Culture switching
• Format string parameters

Related Packages

• LocalizationManager.JsonLocalization - Runtime localization library (required dependency)

License

MIT License - Copyright (c) 2025 Nikolaos Protopapas

Links

• GitHub Repository
• Runtime Package Documentation
• LRM CLI Tool
• VS Code Extension
• Report Issues