abpframework/abp · error · CliUsageException

Failed to get localization information from {targetFile} fil

Error message

Failed to get localization information from {targetFile} file.

What it means

Thrown during online translation (TranslateAbpTranslateInfoAsync) when the target culture JSON file exists on disk but GetAbpLocalizationInfoOrNull returns null. This occurs when the file contains invalid JSON (JObject.Parse throws) or is missing the required 'culture' and/or 'texts' top-level properties. The target file path is constructed as Path.Combine(resource.ResourcePath, translateInfo.TargetCulture + '.json').

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/TranslateCommand.cs:174

        {
            Logger.LogInformation("Include all keys");
        }

        var translateInfo = GetAbpTranslateInfo(directory, targetCulture, referenceCulture, allValues);
        foreach (var resource in translateInfo.Resources)
        {
            var targetFile = Path.Combine(resource.ResourcePath, translateInfo.TargetCulture + ".json");
            var targetLocalizationInfo = File.Exists(targetFile)
                ? GetAbpLocalizationInfoOrNull(targetFile)
                : new AbpLocalizationInfo()
                {
                    Culture = translateInfo.TargetCulture,
                    Texts = new List<NameValue>()
                };

            if (targetLocalizationInfo == null)
            {
                throw new CliUsageException(
                    $"Failed to get localization information from {targetFile} file." +
                    Environment.NewLine + Environment.NewLine +
                    GetUsageInfo()
                );
            }

            var referenceFile = Path.Combine(resource.ResourcePath, translateInfo.ReferenceCulture + ".json");
            if (!File.Exists(referenceFile))
            {
                throw new CliUsageException(
                    $"{referenceFile} file does not exist.." +
                    Environment.NewLine + Environment.NewLine +
                    GetUsageInfo()
                );
            }
            var referenceLocalizationInfo = GetAbpLocalizationInfoOrNull(referenceFile);
            if (referenceLocalizationInfo == null)
            {

View on GitHub (pinned to 7ed43b1931)

Solutions

  1. Validate the target culture JSON file with a JSON linter (e.g., 'jq empty zh-Hans.json')
  2. Ensure the file has both 'culture' and 'texts' top-level properties
  3. Fix any JSON syntax errors (missing commas, trailing commas, unescaped quotes)
  4. If the file is corrupted beyond repair, delete it and let the translate command create a fresh one

Example fix

// before (malformed zh-Hans.json)
{"culture": "zh-Hans", "texts":}

// after (valid)
{"culture": "zh-Hans", "texts": {"Welcome": "欢迎"}}
Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate all target culture JSON files before online translation
foreach (var jsonFile in Directory.GetFiles(localizationDir, $"{targetCulture}.json", SearchOption.AllDirectories))
{
    try
    {
        var obj = JObject.Parse(File.ReadAllText(jsonFile));
        if (obj["culture"] == null || obj["texts"] == null)
            Console.Error.WriteLine($"Warning: {jsonFile} missing 'culture' or 'texts' property");
    }
    catch
    {
        Console.Error.WriteLine($"Error: {jsonFile} is not valid JSON");
    }
}

Type guard

// Check if a JSON file is a valid ABP localization file
public static bool IsValidAbpLocalizationFile(string path)
{
    try
    {
        var obj = JObject.Parse(File.ReadAllText(path));
        return obj["culture"] != null && obj["texts"] != null;
    }
    catch
    {
        return false;
    }
}

Try / catch

try
{
    await TranslateAbpTranslateInfoAsync(directory, targetCulture, referenceCulture, allValues, authKey);
}
catch (CliUsageException ex) when (ex.Message.Contains("Failed to get localization information"))
{
    Console.Error.WriteLine($"Target localization file is invalid. Run 'abp translate --verify' to check.");
}

Prevention

When it happens

Trigger: The target culture JSON file (e.g., zh-Hans.json) exists in a resource directory but is malformed. GetAbpLocalizationInfoOrNull catches the JObject.Parse exception and returns null, or the culture/texts properties are missing, causing the null check at line 172 to fire.

Common situations: Manually edited localization file with syntax errors, BOM or encoding issues, incomplete file from a failed git merge, file from an incompatible ABP version with a different JSON schema, accidental truncation.

Related errors

AI-assisted analysis of abpframework/abp@7ed43b1931 (2026-08-13). Data as JSON: /api/errors/bd77ab6e05ba05ab. Report an issue: GitHub.