feat: Add support for custom_instructions parameter in text translation

Author: BriannaDelgado

README.md

@@ -136,6 +136,13 @@ using the following keys:
     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.
+-   `custom_instructions`: 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 `custom_instructions` parameter enabled will use the
+    `quality_optimized` model type as the default. Requests combining
+    `custom_instructions` and `model_type: latency_optimized` will be rejected.
 -   `glossary`: glossary ID of glossary to use for translation.
 -   `style_id`: specifies a style rule to use with translation, either as a string
     containing the ID of the style rule, or a `StyleRuleInfo` object.

src/TranslateTextOptions.php

@@ -92,4 +92,12 @@ class TranslateTextOptions
      *  @see \DeepL\DeepLClient::getAllStyleRules()
      */
     public const STYLE_ID = 'style_id';
+
+    /** Array of custom instructions to customize text translation behavior. Maximum 10 elements, each max
+     * 300 characters. Only supported for target languages: `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh`
+     * and their variants. Note: using the `custom_instructions` parameter will use the `quality_optimized`
+     * model type as the default. Requests combining `custom_instructions` and the `latency_optimized`
+     * model type will be rejected.
+     */
+    public const CUSTOM_INSTRUCTIONS = 'custom_instructions';
 }

src/Translator.php

@@ -703,6 +703,9 @@ private function validateAndAppendTextOptions(array &$params, ?array $options):
                 throw new DeepLException('style_id must be a string or StyleRuleInfo object');
             }
         }
+        if (isset($options[TranslateTextOptions::CUSTOM_INSTRUCTIONS])) {
+            $params[TranslateTextOptions::CUSTOM_INSTRUCTIONS] = $options[TranslateTextOptions::CUSTOM_INSTRUCTIONS];
+        }
         $this->applyExtraBodyParameters(
             $params,
             $options[TranslateTextOptions::EXTRA_BODY_PARAMETERS] ?? null

tests/TranslateTextTest.php

@@ -415,4 +415,21 @@ public function testExtraBodyParams(?ClientInterface $httpClient)
         $this->assertEquals('en', $result->detectedSourceLang);
         $this->assertEquals(mb_strlen(DeepLTestBase::EXAMPLE_TEXT['en']), $result->billedCharacters);
     }
+
+    /**
+     * @dataProvider provideHttpClient
+     */
+    public function testCustomInstructions(?ClientInterface $httpClient)
+    {
+        $this->needsRealServer();
+        $translator = $this->makeTranslator([TranslatorOptions::HTTP_CLIENT => $httpClient]);
+        $input = "I am testing if custom instructions are working correctly.";
+        $customInstructions = ['Use informal language', 'Be concise'];
+        $resultWithCustomInstructions = $translator->translateText($input, null, 'de', [
+            TranslateTextOptions::CUSTOM_INSTRUCTIONS => $customInstructions
+        ]);
+
+        $resultWithoutCustomInstructions = $translator->translateText($input, null, 'de');
+        $this->assertNotEquals($resultWithoutCustomInstructions->text, $resultWithCustomInstructions->text);
+    }
 }