Add localization support (#229)

Author: ajalt

CHANGELOG.md

@@ -8,9 +8,10 @@
 - Added ability to use unicode NEL character (`\u0085`) to manually break lines in help output ([#214](https://github.com/ajalt/clikt/issues/214))
 - Added `help("")` extension to options and arguments as an alternative to passing the help as an argument ([#207](https://github.com/ajalt/clikt/issues/207))
 - Added `valueSourceKey` parameter to `option`
-- Added `check{}` extensions to options and arguments as an alternative to `validate`
+- Added `check()` extensions to options and arguments as an alternative to `validate()`
 - Added `prompt` and `confirm` functions to `CliktCommand` that call the `TermUi` equivalents with the current console.
 - Added `echo()` overload with no parameters to CliktCommand that prints a newline by itself.
+- Added localization support. You can set an implementation of the `Localization` interface on your context with your translations. ([#227](https://github.com/ajalt/clikt/issues/227))
 
 ### Fixed
 - Hidden options will no longer be suggested as possible typo corrections. ([#202](https://github.com/ajalt/clikt/issues/202))
@@ -22,10 +23,14 @@
 - `Argument.help` and `Option.help` properties have been renamed to `argumentHelp` and `optionHelp`, respectively. The `help` parameter names to `option()` and `argument()` are unchanged.
 - `commandHelp` and `commandHelpEpilog` properties on `CliktCommand` are now `open`, so you can choose to override them instead of passing `help` and `epilog` to the constructor.
 - Replaced `MapValueSource.defaultKey` with `ValueSource.getKey()`, which is more customizable.
+- `Option.metavar`, `Option.parameterHelp`, `OptionGroup.parameterHelp` and `Argument.parameterHelp` properties are now functions.
+- Changed constructor parameters of `CliktHelpFormatter`. Added `localization` and removed `usageTitle`, `optionsTitle`, `argumentsTitle`, `commandsTitle`, `optionsMetavar`, and `commandMetavar`. Those strings are now defined on equivalently named functions on `Localization`.
 
 ### Removed
 - Removed `envvarSplit` parameter from `option()` and `convert()`. Option values from environment variables are no longer split automatically. ([#177](https://github.com/ajalt/clikt/issues/177))
 - Removed public constructors from the following classes: `ProcessedArgument`, `OptionWithValues`, `FlagOption`, `CoOccurringOptionGroup`, `ChoiceGroup`, `MutuallyExclusiveOptions`.
+- `MissingParameter` exception replaced with `MissingOption` and `MissingArgument`
+- Removed `Context.helpOptionMessage`. Override `Localization.helpOptionMessage` and set it on your context instead.
 
 ### Deprecated
 - `@ExperimentalCompletionCandidates` and `@ExperimentalValueSourceApi` annotations. These APIs no longer require an opt-in.

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/CliktCommand.kt

@@ -102,7 +102,7 @@ abstract class CliktCommand(
 
         if (currentContext.helpOptionNames.isNotEmpty()) {
             val names = currentContext.helpOptionNames - registeredOptionNames()
-            if (names.isNotEmpty()) _options += helpOption(names, currentContext.helpOptionMessage)
+            if (names.isNotEmpty()) _options += helpOption(names, currentContext.localization.helpOptionMessage())
         }
 
         for (command in _subcommands) {
@@ -113,9 +113,9 @@ abstract class CliktCommand(
     }
 
     private fun allHelpParams(): List<ParameterHelp> {
-        return _options.mapNotNull { it.parameterHelp } +
-                _arguments.mapNotNull { it.parameterHelp } +
-                _groups.mapNotNull { it.parameterHelp } +
+        return _options.mapNotNull { it.parameterHelp(currentContext) } +
+                _arguments.mapNotNull { it.parameterHelp(currentContext) } +
+                _groups.mapNotNull { it.parameterHelp(currentContext) } +
                 _subcommands.map { ParameterHelp.Subcommand(it.commandName, it.shortHelp(), it.helpTags) }
     }
 
@@ -417,7 +417,7 @@ abstract class CliktCommand(
             echo(e.message, err = true)
             exitProcessMpp(1)
         } catch (e: Abort) {
-            echo("Aborted!", err = true)
+            echo(currentContext.localization.aborted(), err = true)
             exitProcessMpp(if (e.error) 1 else 0)
         }
     }

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/Context.kt

@@ -1,13 +1,9 @@
 package com.github.ajalt.clikt.core
 
-import com.github.ajalt.clikt.output.CliktConsole
-import com.github.ajalt.clikt.output.CliktHelpFormatter
-import com.github.ajalt.clikt.output.HelpFormatter
-import com.github.ajalt.clikt.output.defaultCliktConsole
+import com.github.ajalt.clikt.output.*
 import com.github.ajalt.clikt.sources.ChainedValueSource
 import com.github.ajalt.clikt.sources.ValueSource
 import kotlin.properties.ReadOnlyProperty
-import kotlin.reflect.KProperty
 
 typealias TypoSuggestor = (enteredValue: String, possibleValues: List<String>) -> List<String>
 
@@ -27,7 +23,6 @@ typealias TypoSuggestor = (enteredValue: String, possibleValues: List<String>) -
  * @property helpOptionNames The names to use for the help option. If any names in the set conflict with other
  *   options, the conflicting name will not be used for the help option. If the set is empty, or contains no
  *   unique names, no help option will be added.
- * @property helpOptionMessage The description of the help option.
  * @property helpFormatter The help formatter for this command.
  * @property tokenTransformer An optional transformation function that is called to transform command line
  *   tokens (options and commands) before parsing. This can be used to implement e.g. case insensitive
@@ -46,14 +41,14 @@ class Context(
         val autoEnvvarPrefix: String?,
         val printExtraMessages: Boolean,
         val helpOptionNames: Set<String>,
-        val helpOptionMessage: String,
         val helpFormatter: HelpFormatter,
         val tokenTransformer: Context.(String) -> String,
         val console: CliktConsole,
         val expandArgumentFiles: Boolean,
         val readEnvvarBeforeValueSource: Boolean,
         val valueSource: ValueSource?,
-        val correctionSuggestor: TypoSuggestor
+        val correctionSuggestor: TypoSuggestor,
+        val localization: Localization
 ) {
     var invokedSubcommand: CliktCommand? = null
         internal set
@@ -118,11 +113,8 @@ class Context(
          */
         var helpOptionNames: Set<String> = parent?.helpOptionNames ?: setOf("-h", "--help")
 
-        /** The description of the help option.*/
-        var helpOptionMessage: String = parent?.helpOptionMessage ?: "Show this message and exit"
-
-        /** The help formatter for this command*/
-        var helpFormatter: HelpFormatter = parent?.helpFormatter ?: CliktHelpFormatter()
+        /** The help formatter for this command, or null to use the default */
+        var helpFormatter: HelpFormatter? = parent?.helpFormatter
 
         /** An optional transformation function that is called to transform command line */
         var tokenTransformer: Context.(String) -> String = parent?.tokenTransformer ?: { it }
@@ -180,6 +172,11 @@ class Context(
          * names and filters the list down to values to suggest to the user.
          */
         var correctionSuggestor: TypoSuggestor = DEFAULT_CORRECTION_SUGGESTOR
+
+        /**
+         * Localized strings to use for help output and error reporting.
+         */
+        var localization: Localization = defaultLocalization
     }
 
     companion object {
@@ -188,10 +185,11 @@ class Context(
                 block()
                 val interspersed = allowInterspersedArgs && !command.allowMultipleSubcommands &&
                         parent?.let { p -> p.ancestors().any { it.command.allowMultipleSubcommands } } != true
+                val formatter = helpFormatter ?: CliktHelpFormatter(localization)
                 return Context(
                         parent, command, interspersed, autoEnvvarPrefix, printExtraMessages,
-                        helpOptionNames, helpOptionMessage, helpFormatter, tokenTransformer, console,
-                        expandArgumentFiles, readEnvvarBeforeValueSource, valueSource, correctionSuggestor
+                        helpOptionNames, formatter, tokenTransformer, console, expandArgumentFiles,
+                        readEnvvarBeforeValueSource, valueSource, correctionSuggestor, localization
                 )
             }
         }
@@ -201,21 +199,13 @@ class Context(
 /** Find the closest object of type [T], or throw a [NullPointerException] */
 @Suppress("unused") // these extensions don't use their receiver, but we want to limit where they can be called
 inline fun <reified T : Any> CliktCommand.requireObject(): ReadOnlyProperty<CliktCommand, T> {
-    return object : ReadOnlyProperty<CliktCommand, T> {
-        override fun getValue(thisRef: CliktCommand, property: KProperty<*>): T {
-            return thisRef.currentContext.findObject<T>()!!
-        }
-    }
+    return ReadOnlyProperty<CliktCommand, T> { thisRef, _ -> thisRef.currentContext.findObject<T>()!! }
 }
 
 /** Find the closest object of type [T], or null */
 @Suppress("unused")
 inline fun <reified T : Any> CliktCommand.findObject(): ReadOnlyProperty<CliktCommand, T?> {
-    return object : ReadOnlyProperty<CliktCommand, T?> {
-        override fun getValue(thisRef: CliktCommand, property: KProperty<*>): T? {
-            return thisRef.currentContext.findObject<T>()
-        }
-    }
+    return ReadOnlyProperty { thisRef, _ -> thisRef.currentContext.findObject<T>() }
 }
 
 /**
@@ -228,11 +218,7 @@ inline fun <reified T : Any> CliktCommand.findObject(): ReadOnlyProperty<CliktCo
  */
 @Suppress("unused")
 inline fun <reified T : Any> CliktCommand.findOrSetObject(crossinline default: () -> T): ReadOnlyProperty<CliktCommand, T> {
-    return object : ReadOnlyProperty<CliktCommand, T> {
-        override fun getValue(thisRef: CliktCommand, property: KProperty<*>): T {
-            return thisRef.currentContext.findOrSetObject(default)
-        }
-    }
+    return ReadOnlyProperty { thisRef, _ -> thisRef.currentContext.findOrSetObject(default) }
 }
 
 private val DEFAULT_CORRECTION_SUGGESTOR: TypoSuggestor = { enteredValue, possibleValues ->

clikt/src/commonMain/kotlin/com/github/ajalt/clikt/core/exceptions.kt

@@ -1,5 +1,6 @@
 package com.github.ajalt.clikt.core
 
+import com.github.ajalt.clikt.output.defaultLocalization
 import com.github.ajalt.clikt.parameters.arguments.Argument
 import com.github.ajalt.clikt.parameters.arguments.convert
 import com.github.ajalt.clikt.parameters.options.Option
@@ -85,7 +86,7 @@ open class UsageError private constructor(
 
     fun helpMessage(): String = buildString {
         context?.let { append(it.command.getFormattedUsage()).append("\n\n") }
-        append("Error: ").append(formatMessage())
+        append(localization.usageError(formatMessage()))
     }
 
     override val message: String? get() = formatMessage()
@@ -98,115 +99,125 @@ open class UsageError private constructor(
         argument != null -> argument!!.name
         else -> ""
     }
+
+    protected val localization get() = context?.localization ?: defaultLocalization
 }
 
 /**
  * A parameter was given the correct number of values, but of invalid format or type.
  */
-open class BadParameterValue : UsageError {
+class BadParameterValue : UsageError {
     constructor(text: String, context: Context? = null) : super(text, null, context)
     constructor(text: String, paramName: String, context: Context? = null) : super(text, paramName, context)
     constructor(text: String, argument: Argument, context: Context? = null) : super(text, argument, context)
     constructor(text: String, option: Option, context: Context? = null) : super(text, option, context)
 
     override fun formatMessage(): String {
-        val error = if (text.isNullOrBlank()) "" else ": $text"
-        if (inferParamName().isEmpty()) return "Invalid value$error"
-        return "Invalid value for \"${inferParamName()}\"$error"
+        val m = text.takeUnless { it.isNullOrBlank() }
+        val p = inferParamName().takeIf { it.isNotBlank() }
+
+        return when {
+            m == null && p == null -> localization.badParameter()
+            m == null && p != null -> localization.badParameterWithParam(p)
+            m != null && p == null -> localization.badParameterWithMessage(m)
+            m != null && p != null -> localization.badParameterWithMessageAndParam(p, m)
+            else -> error("impossible")
+        }
     }
 }
 
-/** A required parameter was not provided */
-open class MissingParameter : UsageError {
-    constructor(argument: Argument, context: Context? = null) : super("", argument, context) {
-        this.paramType = "argument"
-    }
-
-    constructor(option: Option, context: Context? = null) : super("", option, context) {
-        this.paramType = "option"
-    }
-
-    private val paramType: String
+/** A required option was not provided */
+class MissingOption(option: Option, context: Context? = null) : UsageError("", option, context) {
+    override fun formatMessage() = localization.missingOption(inferParamName())
+}
 
-    override fun formatMessage(): String {
-        return "Missing $paramType \"${inferParamName()}\"."
-    }
+/** A required argument was not provided */
+class MissingArgument(argument: Argument, context: Context? = null) : UsageError("", argument, context) {
+    override fun formatMessage() = localization.missingArgument(inferParamName())
 }
 
 /** A parameter was provided that does not exist. */
-open class NoSuchParameter(
-        protected val parameterType: String,
-        protected val givenName: String,
-        protected val possibilities: List<String> = emptyList(),
+open class NoSuchParameter protected constructor(context: Context?) : UsageError("", context = context)
+
+/** A subcommand was provided that does not exist. */
+class NoSuchSubcommand(
+        private val givenName: String,
+        private val possibilities: List<String> = emptyList(),
         context: Context? = null
-) : UsageError("", context = context) {
+) : NoSuchParameter(context) {
     override fun formatMessage(): String {
-        return "no such ${parameterType}: \"$givenName\"." + when {
-            possibilities.size == 1 -> " Did you mean \"${possibilities[0]}\"?"
-            possibilities.size > 1 -> possibilities.joinToString(
-                    prefix = " (Possible ${parameterType}s: ", postfix = ")")
-            else -> ""
-        }
+        return localization.noSuchSubcommand(givenName, possibilities)
     }
 }
 
-/** A subcommand was provided that does not exist. */
-open class NoSuchSubcommand(
-        givenName: String,
-        possibilities: List<String> = emptyList(),
-        context: Context? = null
-) : NoSuchParameter("subcommand", givenName, possibilities, context)
-
 
 /** An option was provided that does not exist. */
-open class NoSuchOption(
-        givenName: String,
-        possibilities: List<String> = emptyList(),
+class NoSuchOption(
+        private val givenName: String,
+        private val possibilities: List<String> = emptyList(),
         context: Context? = null
-) : NoSuchParameter("option", givenName, possibilities, context)
+) : NoSuchParameter(context) {
+    override fun formatMessage(): String {
+        return localization.noSuchOption(givenName, possibilities)
+    }
+}
+
 
 /** An option was supplied but the number of values supplied to the option was incorrect. */
-open class IncorrectOptionValueCount(
+class IncorrectOptionValueCount(
         option: Option,
         private val givenName: String,
         context: Context? = null
 ) : UsageError("", option, context) {
     override fun formatMessage(): String {
-        return when (option!!.nvalues) {
-            0 -> "$givenName option does not take a value"
-            1 -> "$givenName option requires an argument"
-            else -> "$givenName option requires ${option!!.nvalues} arguments"
-        }
+        return  localization.incorrectOptionValueCount(givenName, option!!.nvalues)
     }
 }
 
 /** An argument was supplied but the number of values supplied was incorrect. */
-open class IncorrectArgumentValueCount(
+class IncorrectArgumentValueCount(
         argument: Argument,
         context: Context? = null
 ) : UsageError("", argument, context) {
     override fun formatMessage(): String {
-        return "argument ${inferParamName()} takes ${argument!!.nvalues} values"
+        return localization.incorrectArgumentValueCount(inferParamName(), argument!!.nvalues)
     }
 }
 
-open class MutuallyExclusiveGroupException(
-        protected val names: List<String>,
+class MutuallyExclusiveGroupException(
+        private val names: List<String>,
         context: Context? = null
 ) : UsageError("", context = context) {
     init {
         require(names.size > 1) { "must provide at least two names" }
     }
 
     override fun formatMessage(): String {
-        return "option ${names.first()} cannot be used with ${names.drop(1).joinToString(" or ")}"
+        return localization.mutexGroupException(names.first(), names.drop(1))
     }
 }
 
 /** A required configuration file was not found. */
-class FileNotFound(filename: String) : UsageError("$filename not found")
+class FileNotFound(
+        private val filename: String,
+        context: Context? = null
+) : UsageError("", context = context) {
+    override fun formatMessage(): String {
+        return localization.fileNotFound(filename)
+    }
+}
 
 /** A configuration file failed to parse correctly */
-class InvalidFileFormat(filename: String, message: String, lineno: Int? = null) : UsageError(
-        "incorrect format in file $filename${lineno?.let { " line $it" } ?: ""}}: $message"
-)
+class InvalidFileFormat(
+        private val filename: String,
+        message: String,
+        private val lineno: Int? = null,
+        context: Context? = null
+) : UsageError(message, context = context) {
+    override fun formatMessage(): String {
+        return when (lineno) {
+            null -> localization.invalidFileFormat(filename, text!!)
+            else -> localization.invalidFileFormat(filename, lineno, text!!)
+        }
+    }
+}