fix: validate spoken terms like glossary terms

Terms are joined with newlines on the wire, so a term containing a newline
was silently sent as several terms. createSpokenTerms(), updateSpokenTerms()
and replaceSpokenTermsList() now check each term with
GlossaryEntries.validateGlossaryTerm() before any request and throw the same
IllegalArgumentException as the glossary methods.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: 2 people

CHANGELOG.md

@@ -11,7 +11,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `updateSpokenTerms()`, `getSpokenTermsEntries()`, `replaceSpokenTermsList()`,
   `deleteSpokenTerms()` and `deleteSpokenTermsList()`, with the new classes
   `SpokenTerms`, `SpokenTermsList` and `SpokenTermsEntries`. Terms are passed
-  and returned as a list of strings.
+  and returned as a list of strings and are checked like glossary terms, so a
+  term containing a newline throws an `IllegalArgumentException`.
 - Added the API Pro fields of `GET /v2/usage` to `Usage`:
   `getApiKeyCharacter()` (per-key character usage), `getSpeechToTextMinutes()`,
   `getSpeechToSpeechMinutes()`, `getStartTime()` and `getEndTime()` (billing

README.md

@@ -691,7 +691,9 @@ collections can be stored with your account, each with a user-specified name
 and a uniquely-assigned ID.
 
 Each method that takes a collection accepts either its ID or a `SpokenTerms`
-object. The terms are not validated client-side; the API rejects invalid terms
+object. Terms are checked like glossary terms before any request is sent: a
+term that is empty or contains a control character such as a newline throws an
+`IllegalArgumentException`. Other invalid term lists are rejected by the API
 with a `DeepLException`.
 
 #### Creating a Spoken Terms collection

deepl-java/src/main/java/com/deepl/api/DeepLClient.java

@@ -782,6 +782,7 @@ public void deleteMultilingualGlossaryDictionary(
    * @param name User-defined name of the collection.
    * @param termLists Term lists of the collection, one {@link SpokenTermsEntries} per language.
    * @return {@link SpokenTerms} object with details about the new collection.
+   * @throws IllegalArgumentException If a term is invalid, as checked for glossary terms.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
    * @throws DeepLException If any error occurs while communicating with the DeepL API, a {@link
    *     DeepLException} or a derived class will be thrown.
@@ -856,6 +857,7 @@ public SpokenTerms getSpokenTerms(SpokenTerms spokenTerms)
    *     current term lists.
    * @return {@link SpokenTerms} object with details about the updated collection.
    * @throws NotFoundException If no collection with the given ID is found.
+   * @throws IllegalArgumentException If a term is invalid, as checked for glossary terms.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
    * @throws DeepLException If any error occurs while communicating with the DeepL API.
    */
@@ -929,6 +931,7 @@ public SpokenTermsEntries getSpokenTermsEntries(SpokenTerms spokenTerms, String
    * @param entries Language and terms of the new term list.
    * @return {@link SpokenTermsList} object with details about the new term list.
    * @throws NotFoundException If no collection with the given ID is found.
+   * @throws IllegalArgumentException If a term is invalid, as checked for glossary terms.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
    * @throws DeepLException If any error occurs while communicating with the DeepL API.
    */
@@ -1716,8 +1719,14 @@ private static String langQueryString(String lang) {
     return createQueryString(queryParams);
   }
 
-  /** Builds the JSON object of one term list; the API expects the terms newline-separated. */
+  /**
+   * Builds the JSON object of one term list; the API expects the terms newline-separated, so each
+   * term is checked like a glossary term first: a term containing a newline would split.
+   */
   private static Map<String, Object> createSpokenTermsListData(SpokenTermsEntries entries) {
+    for (String term : entries.getEntries()) {
+      GlossaryEntries.validateGlossaryTerm(term);
+    }
     Map<String, Object> data = new LinkedHashMap<>();
     data.put("lang", entries.getLang());
     data.put("entries", String.join("\n", entries.getEntries()));

deepl-java/src/offlineTest/java/com/deepl/api/SpokenTermsTest.java

@@ -3,14 +3,19 @@
 // license that can be found in the LICENSE file.
 package com.deepl.api;
 
+import static com.github.tomakehurst.wiremock.client.WireMock.anyRequestedFor;
+import static com.github.tomakehurst.wiremock.client.WireMock.anyUrl;
 import static com.github.tomakehurst.wiremock.client.WireMock.equalToJson;
 import static com.github.tomakehurst.wiremock.client.WireMock.get;
 import static com.github.tomakehurst.wiremock.client.WireMock.okJson;
 import static com.github.tomakehurst.wiremock.client.WireMock.put;
 import static com.github.tomakehurst.wiremock.client.WireMock.urlEqualTo;
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 
@@ -35,4 +40,18 @@ void joinsEntriesWithNewlinesWhenSendingAndSplitsThemWhenReading() throws Except
     assertEquals("en", entries.getLang());
     assertEquals(Arrays.asList("a", "b"), entries.getEntries());
   }
+
+  @Test
+  void rejectsATermContainingANewlineBeforeSendingAnyRequest() {
+    List<SpokenTermsEntries> termLists =
+        Collections.singletonList(new SpokenTermsEntries("en", Arrays.asList("DeepL", "a\nb")));
+
+    assertThrows(IllegalArgumentException.class, () -> client.createSpokenTerms("n", termLists));
+    assertThrows(
+        IllegalArgumentException.class, () -> client.updateSpokenTerms("st1", null, termLists));
+    assertThrows(
+        IllegalArgumentException.class,
+        () -> client.replaceSpokenTermsList("st1", termLists.get(0)));
+    wm.verify(0, anyRequestedFor(anyUrl()));
+  }
 }