abpframework/abp · error · CliUsageException

{referenceFile} file does not exist..

Error message

{referenceFile} file does not exist..

What it means

Thrown during online translation (TranslateAbpTranslateInfoAsync) when the reference culture JSON file does not exist on disk. The reference file path is constructed as Path.Combine(resource.ResourcePath, translateInfo.ReferenceCulture + '.json'). The reference culture defaults to 'en' unless overridden with -r/--reference-culture. Note: the error message has a double-period typo ('exist..').

Source

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

                : 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)
            {
                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);

View on GitHub (pinned to 7ed43b1931)

Solutions

  1. Verify the reference culture file (e.g., en.json) exists in the localization directory
  2. Specify the correct reference culture with -r/--reference-culture (use .NET culture names like 'en', 'de', 'tr')
  3. Ensure all reference culture JSON files are committed to version control
  4. Run 'abp translate --verify' to check all localization files for issues

Example fix

// before
abp translate -c zh-Hans -r english --online --deepl-auth-key KEY

// after (use valid .NET culture name)
abp translate -c zh-Hans -r en --online --deepl-auth-key KEY
Defensive patterns

Strategy: validation

Validate before calling

// Pre-check that reference culture file exists
var referenceFile = Path.Combine(resourcePath, referenceCulture + ".json");
if (!File.Exists(referenceFile))
{
    Console.Error.WriteLine($"Error: Reference file not found: {referenceFile}");
    return;
}

Try / catch

try
{
    await TranslateAbpTranslateInfoAsync(directory, targetCulture, referenceCulture, allValues, authKey);
}
catch (CliUsageException ex) when (ex.Message.Contains("file does not exist"))
{
    Console.Error.WriteLine($"Reference culture file missing. Ensure {referenceCulture}.json exists in all localization directories.");
}

Prevention

When it happens

Trigger: Running 'abp translate -c <culture> --online --deepl-auth-key <key>' when the reference culture JSON file (default: en.json) is missing from one or more resource directories discovered during the scan.

Common situations: Reference culture files not committed to the repo, renamed or moved, reference culture misspelled with -r (e.g., '-r english' instead of '-r en'), project structure doesn't include the default 'en' localization files.

Related errors

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