abpframework/abp · error · CliUsageException

Failed to get localization information from {referenceFile}

Error message

Failed to get localization information from {referenceFile} file.

What it means

Thrown during online translation (TranslateAbpTranslateInfoAsync) when the reference culture JSON file exists but GetAbpLocalizationInfoOrNull returns null. Same parsing failure as error 173 but for the reference file instead of the target. The file exists (File.Exists returned true at line 182) but its content is invalid JSON or lacks the 'culture'/'texts' properties.

Source

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

                    $"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)
            {
                throw new CliUsageException(
                    $"Failed to get localization information from {referenceFile} file." +
                    Environment.NewLine + Environment.NewLine +
                    GetUsageInfo()
                );
            }

            var translator = new Translator(authKey);

            var texts = resource.Texts.Select(x => x.Reference);

            var translations = await translator.TranslateTextAsync(texts, await GetDeeplLanguageCode(referenceCulture), await GetDeeplLanguageCode(targetCulture));
            for (var i = 0; i < translations.Length; i++)
            {
                resource.Texts[i].Target = translations[i].Text;
            }

            foreach (var text in resource.Texts)
            {

View on GitHub (pinned to 7ed43b1931)

Solutions

  1. Validate the reference JSON file with a JSON linter
  2. Ensure the file has both 'culture' and 'texts' top-level properties
  3. Restore the file from version control if corrupted
  4. Run 'abp translate --verify' to identify which files have JSON issues

Example fix

// before (malformed en.json)
{"culture": "en", "texts":}

// after (valid)
{"culture": "en", "texts": {"Welcome": "Welcome"}}
Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate reference culture JSON files
foreach (var refFile in Directory.GetFiles(localizationDir, $"{referenceCulture}.json", SearchOption.AllDirectories))
{
    try
    {
        var obj = JObject.Parse(File.ReadAllText(refFile));
        if (obj["culture"] == null || obj["texts"] == null)
            Console.Error.WriteLine($"Warning: {refFile} missing required properties");
    }
    catch
    {
        Console.Error.WriteLine($"Error: {refFile} is not valid JSON");
    }
}

Type guard

// Check if reference file is valid ABP localization JSON
public static bool IsValidReferenceLocalization(string path)
{
    if (!File.Exists(path)) return false;
    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") && ex.Message.Contains(referenceCulture))
{
    Console.Error.WriteLine($"Reference localization file is corrupted. Restore from version control.");
}

Prevention

When it happens

Trigger: The reference culture JSON file (e.g., en.json) exists in a resource directory but is malformed. GetAbpLocalizationInfoOrNull returns null after failing JObject.Parse or finding missing culture/texts properties.

Common situations: Corrupted reference localization file, non-ABP format JSON file accidentally placed in the localization directory, manually edited file with syntax errors, file from an incompatible ABP version.

Related errors

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