abpframework/abp · error · CliUsageException

Target culture is missing!

Error message

Target culture is missing!

What it means

Thrown by TranslateCommand.ExecuteAsync when the -c/--culture option is not provided AND neither --apply/-a nor --verify is set. The target culture specifies which language to translate into (e.g., 'zh-Hans', 'de', 'tr'). It is required for both translation generation and online translation modes. The only mode that doesn't require it is --apply (which reads culture from the translation file).

Source

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

            await VerifyJsonAsync(currentDirectory);
            return;
        }

        var referenceCulture = commandLineArgs.Options.GetOrNull(Options.ReferenceCulture.Short, Options.ReferenceCulture.Long) ?? "en";
        var allValues = commandLineArgs.Options.ContainsKey(Options.AllValues.Short) || commandLineArgs.Options.ContainsKey(Options.AllValues.Long);

        // Apply abp-translation.json file
        if (commandLineArgs.Options.ContainsKey(Options.Apply.Short) || commandLineArgs.Options.ContainsKey(Options.Apply.Long))
        {
            var inputFile = Path.Combine(currentDirectory, commandLineArgs.Options.GetOrNull(Options.File.Short, Options.File.Long) ?? "abp-translation.json");
            await ApplyAbpTranslateInfoAsync(currentDirectory, inputFile);
            return;
        }

        var targetCulture = commandLineArgs.Options.GetOrNull(Options.Culture.Short, Options.Culture.Long);
        if (targetCulture == null)
        {
            throw new CliUsageException("Target culture is missing!" + Environment.NewLine + Environment.NewLine + GetUsageInfo());
        }

        // Translate online
        if (commandLineArgs.Options.ContainsKey(Options.Online.Long))
        {
            var authKey = commandLineArgs.Options.GetOrNull(Options.DeepLAuthKey.Short, Options.DeepLAuthKey.Short);
            if (authKey == null)
            {
                throw new CliUsageException("DeepL auth key is missing!" + Environment.NewLine + Environment.NewLine + GetUsageInfo());
            }
            await TranslateAbpTranslateInfoAsync(currentDirectory, targetCulture, referenceCulture, allValues, authKey);
            return;
        }

        // Generate abp-translation.json file
        var outputFile = Path.Combine(currentDirectory, commandLineArgs.Options.GetOrNull(Options.Output.Short, Options.Output.Long) ?? "abp-translation.json");
        await GenerateAbpTranslateInfoAsync(currentDirectory, targetCulture, referenceCulture, allValues, outputFile);
    }

View on GitHub (pinned to 7ed43b1931)

Solutions

  1. Add --culture <culture-name> (e.g., --culture zh-Hans, --culture de, --culture tr)
  2. If applying a previously generated translation file, use --apply instead of --culture
  3. Run 'abp help translate' to see all available options

Example fix

// before
abp translate

// after
abp translate --culture zh-Hans
Defensive patterns

Strategy: validation

Validate before calling

// Validate that culture is provided when not in apply mode
var isApply = commandLineArgs.Options.ContainsKey("a") || commandLineArgs.Options.ContainsKey("apply");
var isVerify = commandLineArgs.Options.ContainsKey("verify");
var hasCulture = commandLineArgs.Options.ContainsKey("c") || commandLineArgs.Options.ContainsKey("culture");

if (!isApply && !isVerify && !hasCulture)
{
    Console.Error.WriteLine("Error: --culture is required (or use --apply / --verify).");
    return;
}

Try / catch

try
{
    await translateCommand.ExecuteAsync(commandLineArgs);
}
catch (CliUsageException ex) when (ex.Message.Contains("Target culture is missing"))
{
    Console.Error.WriteLine("Missing --culture. Example: abp translate -c zh-Hans");
}

Prevention

When it happens

Trigger: Running 'abp translate' without --culture and without --apply. For example: 'abp translate' alone, or 'abp translate --all-values' without a culture.

Common situations: Developer forgets to specify the target culture, misunderstands that --apply and --culture are different modes, or expects the command to prompt interactively.

Related errors

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