Localization: split to json files

[antonGritsenko]

Hello

The current implementation of the standard localization engine is quite good, except one thing: if you have big module with a lot of strings, handling this starts to be a nightmare. What the reason behind this decision? Why you don't allow to split localization to different file like de_Book.json, de_Author.json and so on? This will create a lot of flexibility to organize translations.

The implementation also will not be hard (I can add PR if it's OK), I did it already for my own project, but it's big overhead, because I need to implement the entire logic from scratch. The reason is implementation of the ILocalizationResourceContributor checking if language code already exists and thru the error instead just combine. Implementation of the

abp/framework/src/Volo.Abp.Localization/Volo/Abp/Localization/StaticLocalizationDictionary.cs

Line 9 in 7977855

public class StaticLocalizationDictionary : ILocalizationDictionary

also don't have methods to combine.

I did my own like that (see Merge method):

public class OpenStaticLocalizationDictionary : ILocalizationDictionary
{
    /// <inheritdoc/>
    public string CultureName { get; }

    public Dictionary<string, LocalizedString> Dictionary { get; }

    /// <summary>
    /// Creates a new <see cref="OpenStaticLocalizationDictionary"/> object.
    /// </summary>
    /// <param name="cultureName">Culture of the dictionary</param>
    /// <param name="dictionary">The dictionary</param>
    public OpenStaticLocalizationDictionary(string cultureName, Dictionary<string, LocalizedString> dictionary)
    {
        CultureName = cultureName;
        Dictionary = dictionary;
    }

    /// <inheritdoc/>
    public virtual LocalizedString? GetOrNull(string name)
    {
        return Dictionary.GetOrDefault(name);
    }

    public void Fill(Dictionary<string, LocalizedString> dictionary)
    {
        foreach (var item in Dictionary)
        {
            dictionary[item.Key] = item.Value;
        }
    }

    public void Merge(OpenStaticLocalizationDictionary dictionary)
    {
        foreach (var item in dictionary.Dictionary)
        {
            Dictionary[item.Key] = item.Value;
        }
    }
}

[maliming]

Hi,

Thanks for the detailed analysis and the workaround you've already implemented. This is a valid use case — large modules can end up with hundreds of localization keys in a single file, and splitting by entity/feature is a reasonable way to keep things maintainable.

We're open to accepting a PR for this. A few things to keep in mind:

1. Merge strategy for duplicate keys: When the same key exists in multiple files for the same culture, the behavior should be clearly defined. We suggest the last loaded file wins (later file overrides earlier), but please make this clear in the code with a comment.

2. File loading order: The merge result depends on the order files are loaded. Currently, files are iterated via IVirtualFileProvider.GetDirectoryContents(), which follows the filesystem order. This should be documented so users know what to expect.

3. StaticLocalizationDictionary changes: Instead of rebuilding the dictionary using a temporary Dictionary<string, LocalizedString> in CreateDictionaries(), consider adding a Merge method to StaticLocalizationDictionary to make the intent explicit and the code cleaner.

4. Tests: Please add unit tests covering the multi-file merge scenario, including the duplicate key case.

Feel free to open a PR — we'll review it.

Thanks

[antonGritsenko]

@maliming thanks for inputs. About point 1, I don't think we need to change current behavior. Having same keys is not something that should be the case, and throw the error like it now is fine:

abp/framework/src/Volo.Abp.Localization/Volo/Abp/Localization/Json/JsonLocalizationDictionaryBuilder.cs

Lines 78 to 83 in c08dbb0

	if (dublicateNames.Count > 0)
	{
	throw new AbpException(
	"A dictionary can not contain same key twice. There are some duplicated names: " +
	dublicateNames.JoinAsString(", "));
	}

[maliming]

Hi,

Good point — I agree. Keeping the exception for duplicate keys across files is the safer approach. The purpose of splitting files is organizing keys, not overriding them. Throwing an error when the same key appears in multiple files will help users catch unintentional duplicates early.

Looking forward to your PR.

Thanks

[antonGritsenko]

@maliming I'm thinking about this check:

abp/framework/src/Volo.Abp.Localization/Volo/Abp/Localization/Json/JsonLocalizationDictionaryBuilder.cs

Lines 78 to 83 in c08dbb0

	if (dublicateNames.Count > 0)
	{
	throw new AbpException(
	"A dictionary can not contain same key twice. There are some duplicated names: " +
	dublicateNames.JoinAsString(", "));
	}

and can't find any case then this check will make sense.

• When texts are simple strings last value always win, this is how default serialization works
• When texts are json object it will have same behavior thanks to

  abp/framework/src/Volo.Abp.Localization/Volo/Abp/Localization/Json/JsonLocalizationDictionaryBuilder.cs

  Line 99 in c08dbb0

  result[item.Key] = item.Value;

Sample for second case:

       var input = @"{
""culture"": ""en"",
""texts"": {
   ""ThisFieldIsRequired"": ""This field is required"",
   ""DeepLocaliaztionKey"": {""DeepKey"": ""DeepValue""},
   ""DeepLocaliaztionKey__DeepKey"": ""Another translation""
}
}";

       var localizationDictionary = JsonLocalizationDictionaryBuilder.BuildFromJsonString(input);
       localizationDictionary.ShouldNotBeNull();
       var localizationString = localizationDictionary.GetOrNull("DeepLocaliaztionKey__DeepKey");
       localizationString.ShouldNotBeNull();
       localizationString.Value.ShouldBe("Another translation");

Do you know why this check was added?

Actully, this even can't be the case because of nature of the FlattenTexts - it return Dictionary<string, string>, so can't have same keys.

[maliming]

Hi,

You are right — this check is likely a leftover from earlier JSON library behavior that may have handled duplicate keys differently. It is effectively dead code now.

Feel free to keep it or remove it in your PR — it is not a big deal either way.

Thanks

[antonGritsenko]

PR added #25227