feat: add billed characters to translate text response

Author: daniel-jones-dev

CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+### Added
+* Added `getBilledCharacters()` to text translation response.
+
+
 ## [1.5.1] - 2024-09-05
 ### Fixed
 * Fixed parsing for usage count and limit for large values.
@@ -110,6 +115,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Initial version.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-java/compare/v1.5.1...HEAD
 [1.5.1]: https://github.com/DeepLcom/deepl-java/compare/v1.5.0...v1.5.1
 [1.5.0]: https://github.com/DeepLcom/deepl-java/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/DeepLcom/deepl-java/compare/v1.3.0...v1.4.0

README.md

@@ -96,9 +96,10 @@ There are additional optional arguments to control translation, see
 [Text translation options](#text-translation-options) below.
 
 `translateText()` returns a `TextResult`, or a List of `TextResult`s
-corresponding to your input text(s). `TextResult` has two accessors: `getText()`
-returns the translated text, and `getDetectedSourceLanguage()` returns the
-detected source language code.
+corresponding to your input text(s). `TextResult` has the following accessors:
+- `getText()` returns the translated text,
+- `getDetectedSourceLanguage()` returns the detected source language code, and
+- `getBilledCharacters()` returns the number of characters billed for the text.
 
 ```java
 class Example {  // Continuing class Example from above
@@ -115,8 +116,10 @@ class Example {  // Continuing class Example from above
                                          "en-GB");
         System.out.println(results.get(0).getText()); // "How are you?"
         System.out.println(results.get(0).getDetectedSourceLanguage()); // "ja" the language code for Japanese
+        System.out.println(results.get(0).getBilledCharacters()); // 7 - the number of characters in the source text "お元気ですか？"
         System.out.println(results.get(1).getText()); // "How are you?"
         System.out.println(results.get(1).getDetectedSourceLanguage()); // "es" the language code for Spanish
+        System.out.println(results.get(1).getBilledCharacters()); // 12 - the number of characters in the source text "¿Cómo estás?"
 
         // Translate into German with less and more Formality:
         System.out.println(translator.translateText("How are you?",

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

@@ -7,11 +7,13 @@
 public class TextResult {
   private final String text;
   private final String detectedSourceLanguage;
+  private final int billedCharacters;
 
   /** Constructs a new instance. */
-  public TextResult(String text, String detectedSourceLanguage) {
+  public TextResult(String text, String detectedSourceLanguage, int billedCharacters) {
     this.text = text;
     this.detectedSourceLanguage = LanguageCode.standardize(detectedSourceLanguage);
+    this.billedCharacters = billedCharacters;
   }
 
   /** The translated text. */
@@ -23,4 +25,9 @@ public String getText() {
   public String getDetectedSourceLanguage() {
     return detectedSourceLanguage;
   }
+
+  /** Number of characters billed for this text. */
+  public int getBilledCharacters() {
+    return billedCharacters;
+  }
 }

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

@@ -782,6 +782,8 @@ private static ArrayList<KeyValuePair<String, String>> createHttpParams(
           if (text.isEmpty()) throw new IllegalArgumentException("text must not be empty");
           params.add(new KeyValuePair<>("text", text));
         });
+    // Always send show_billed_characters=1, remove when the API default is changed to true
+    params.add(new KeyValuePair<>("show_billed_characters", "1"));
 
     if (options != null) {
       // Note: formality and glossaryId are added above

deepl-java/src/main/java/com/deepl/api/parsing/TextResultDeserializer.java

@@ -18,6 +18,7 @@ public TextResult deserialize(JsonElement json, Type typeOfT, JsonDeserializatio
     JsonObject jsonObject = json.getAsJsonObject();
     return new TextResult(
         jsonObject.get("text").getAsString(),
-        jsonObject.get("detected_source_language").getAsString());
+        jsonObject.get("detected_source_language").getAsString(),
+        jsonObject.get("billed_characters").getAsInt());
   }
 }

deepl-java/src/test/java/com/deepl/api/GeneralTest.java

@@ -45,6 +45,7 @@ void testExampleTranslation() throws DeepLException, InterruptedException {
       String sourceLang = LanguageCode.removeRegionalVariant(entry.getKey());
       TextResult result = translator.translateText(inputText, sourceLang, "en-US");
       Assertions.assertTrue(result.getText().toLowerCase(Locale.ENGLISH).contains("proton"));
+      Assertions.assertEquals(inputText.length(), result.getBilledCharacters());
     }
   }
 

deepl-java/src/test/java/com/deepl/api/TranslateTextTest.java

@@ -17,6 +17,7 @@ void testSingleText() throws DeepLException, InterruptedException {
     TextResult result = translator.translateText(exampleText.get("en"), null, LanguageCode.German);
     Assertions.assertEquals(exampleText.get("de"), result.getText());
     Assertions.assertEquals("en", result.getDetectedSourceLanguage());
+    Assertions.assertEquals(exampleText.get("en").length(), result.getBilledCharacters());
   }
 
   @Test