Skip to content

Commit c9e9132

Browse files
hive-botclaude
authored andcommitted
feat: add the Spoken Terms API to DeepLClient
Add createSpokenTerms(), listSpokenTerms(), getSpokenTerms(), updateSpokenTerms(), getSpokenTermsEntries(), replaceSpokenTermsList(), deleteSpokenTerms() and deleteSpokenTermsList() for /v3/spoken-terms, with the SpokenTerms, SpokenTermsList and SpokenTermsEntries models. Terms are a list of strings; they are joined with newlines on the wire and split again when read. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 0aa21a1 commit c9e9132

12 files changed

Lines changed: 732 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
66

77
## [Unreleased]
88
### Added
9+
- Added Spoken Terms support to `DeepLClient` (`/v3/spoken-terms`):
10+
`createSpokenTerms()`, `listSpokenTerms()`, `getSpokenTerms()`,
11+
`updateSpokenTerms()`, `getSpokenTermsEntries()`, `replaceSpokenTermsList()`,
12+
`deleteSpokenTerms()` and `deleteSpokenTermsList()`, with the new classes
13+
`SpokenTerms`, `SpokenTermsList` and `SpokenTermsEntries`. Terms are passed
14+
and returned as a list of strings.
915
- Added the API Pro fields of `GET /v2/usage` to `Usage`:
1016
`getApiKeyCharacter()` (per-key character usage), `getSpeechToTextMinutes()`,
1117
`getSpeechToSpeechMinutes()`, `getStartTime()` and `getEndTime()` (billing

‎README.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -682,6 +682,101 @@ class Example { // Continuing class Example from above
682682
The `translateDocument()` and `translateDocumentUpload()` functions both
683683
support the `glossary` argument.
684684

685+
### Spoken Terms
686+
687+
Spoken Terms collections improve the transcription of terms such as product
688+
names and technical vocabulary. A collection holds one term list per language
689+
(ISO 639-1 code, for example `en`); each term list is a list of terms. Multiple
690+
collections can be stored with your account, each with a user-specified name
691+
and a uniquely-assigned ID.
692+
693+
Each method that takes a collection accepts either its ID or a `SpokenTerms`
694+
object. The terms are not validated client-side; the API rejects invalid terms
695+
with a `DeepLException`.
696+
697+
#### Creating a Spoken Terms collection
698+
699+
Use `createSpokenTerms()` with a name and a list of `SpokenTermsEntries`, one
700+
per language. It returns a `SpokenTerms` object with the ID, name, creation
701+
time and the term lists (`SpokenTermsList`: language and entry count):
702+
703+
```java
704+
class Example { // Continuing class Example from above
705+
public void createSpokenTermsExample() throws Exception {
706+
SpokenTerms spokenTerms = client.createSpokenTerms(
707+
"Technical Terms",
708+
Arrays.asList(new SpokenTermsEntries("en", Arrays.asList("DeepL", "API", "webhook"))));
709+
System.out.println("Created " + spokenTerms.getSpokenTermsId());
710+
for (SpokenTermsList termList : spokenTerms.getTermLists()) {
711+
System.out.println(termList.getLang() + ": " + termList.getEntryCount() + " terms");
712+
}
713+
}
714+
}
715+
```
716+
717+
#### Getting and listing Spoken Terms collections
718+
719+
`getSpokenTerms()` retrieves one collection, `listSpokenTerms()` all of them.
720+
Neither returns the terms themselves; use `getSpokenTermsEntries()` with a
721+
language code for those:
722+
723+
```java
724+
class Example { // Continuing class Example from above
725+
public void getSpokenTermsExample() throws Exception {
726+
SpokenTerms spokenTerms = client.getSpokenTerms("def3a26b-3e84-45b3-84ae-0c0aaf3525f7");
727+
System.out.println(spokenTerms.getName() + " " + spokenTerms.getCreationTime());
728+
729+
for (SpokenTerms collection : client.listSpokenTerms()) {
730+
System.out.println(collection.getName() + " (" + collection.getSpokenTermsId() + ")");
731+
}
732+
733+
SpokenTermsEntries entries = client.getSpokenTermsEntries(spokenTerms, "en");
734+
System.out.println(entries.getEntries()); // [API, DeepL, webhook]
735+
}
736+
}
737+
```
738+
739+
#### Editing a Spoken Terms collection
740+
741+
`updateSpokenTerms()` changes the name and/or merges terms into the existing
742+
term lists; pass `null` for what should not change. `replaceSpokenTermsList()`
743+
replaces the term list of one language, or adds it if the collection has none
744+
for that language. `deleteSpokenTermsList()` removes the term list of one
745+
language:
746+
747+
```java
748+
class Example { // Continuing class Example from above
749+
public void editSpokenTermsExample() throws Exception {
750+
String spokenTermsId = "def3a26b-3e84-45b3-84ae-0c0aaf3525f7";
751+
752+
// Rename the collection
753+
client.updateSpokenTerms(spokenTermsId, "Product Terms", null);
754+
755+
// Merge a term into the "en" term list
756+
SpokenTerms updated = client.updateSpokenTerms(spokenTermsId, null,
757+
Arrays.asList(new SpokenTermsEntries("en", Arrays.asList("authentication"))));
758+
759+
// Replace the "en" term list, then add and remove a "de" term list
760+
SpokenTermsList replaced = client.replaceSpokenTermsList(spokenTermsId,
761+
new SpokenTermsEntries("en", Arrays.asList("API")));
762+
System.out.println(replaced.getEntryCount()); // 1
763+
client.replaceSpokenTermsList(spokenTermsId,
764+
new SpokenTermsEntries("de", Arrays.asList("Schnittstelle")));
765+
client.deleteSpokenTermsList(spokenTermsId, "de");
766+
}
767+
}
768+
```
769+
770+
#### Deleting a Spoken Terms collection
771+
772+
```java
773+
class Example { // Continuing class Example from above
774+
public void deleteSpokenTermsExample() throws Exception {
775+
client.deleteSpokenTerms("def3a26b-3e84-45b3-84ae-0c0aaf3525f7");
776+
}
777+
}
778+
```
779+
685780
### Style Rules
686781

687782
Style rules allow you to customize your translations using a managed, shared list

0 commit comments

Comments
 (0)