feat: Add support for custom_instructions parameter in text translation

Author: BriannaDelgado

DeepL/TextTranslateOptions.cs

@@ -81,5 +81,11 @@ public TextTranslateOptions(StyleRuleInfo styleRule) : this() {
     /// </summary>
     /// <seealso cref="ModelType" />
     public ModelType? ModelType { get; set; }
+
+    /// <summary>
+    ///   A list of custom instructions to guide the translation.
+    ///   Maximum of 10 instructions, each with a maximum length of 300 characters.
+    /// </summary>
+    public List<string> CustomInstructions { get; } = new List<string>();
   }
 }

DeepL/Translator.cs

@@ -956,6 +956,12 @@ private String ConstructUserAgentString(bool sendPlatformInfo = true, AppInfo? a
         bodyParams.Add(("model_type", options.ModelType.Value.ToApiValue()));
       }
 
+      if (options.CustomInstructions.Count > 0) {
+        foreach (var instruction in options.CustomInstructions) {
+          bodyParams.Add(("custom_instructions", instruction));
+        }
+      }
+
       AddExtraBodyParameters(bodyParams, options.ExtraBodyParameters);
 
       return bodyParams;

DeepLTests/TranslateTextTest.cs

@@ -354,5 +354,29 @@ public async Task TestExtraBodyParametersAllowsOverride() {
       Assert.Equal("en", result.DetectedSourceLanguageCode);
       Assert.Equal(ExampleText("en").Length, result.BilledCharacters);
     }
+
+    [RealServerOnlyFact]
+    public async Task TestCustomInstructions() {
+      var translator = CreateTestTranslator();
+      var options = new TextTranslateOptions();
+      var text = "I am testing if custom instructions are working correctly.";
+      options.CustomInstructions.Add("Use informal language");
+      options.CustomInstructions.Add("Be concise");
+
+      var result_with_custom_instructions = await translator.TranslateTextAsync(
+            text,
+            null,
+            "DE",
+            options);
+
+      var result_without_custom_instructions = await translator.TranslateTextAsync(
+            text,
+            null,
+            "DE");
+
+      Assert.NotNull(result_with_custom_instructions);
+      Assert.NotNull(result_with_custom_instructions.Text);
+      Assert.NotEqual(result_with_custom_instructions.Text, result_without_custom_instructions.Text);
+    }
   }
 }

README.md

@@ -139,6 +139,13 @@ foreach (var formality in new[] { Formality.Less, Formality.More }) {
   translated itself. Characters in the `context` parameter are not counted toward billing.
   See the [API documentation][api-docs-context-param] for more information and
   example usage.
+- `CustomInstructions`: an array of instructions to customize the translation behavior.
+  Up to 10 custom instructions can be specified, each with a maximum of 300 characters.
+  Important: The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh`
+  or any variants of these languages.
+  Note: Any request with the `CustomInstructions` parameter enabled will use
+  `quality_optimized` models as the default. Requests combining 
+  `CustomInstructions` and `ModelType: latency_optimized` will be rejected.
 - `ModelType`: specifies the type of translation model to use, options are:
   - `'quality_optimized'` (`ModelType.QualityOptimized`): use a translation
     model that maximizes translation quality, at the cost of response time.