{"id":28419369,"url":"https://github.com/deeplcom/deepl-java","last_synced_at":"2025-06-27T01:31:38.452Z","repository":{"id":60215926,"uuid":"530168999","full_name":"DeepLcom/deepl-java","owner":"DeepLcom","description":"Official Java library for the DeepL language translation API.","archived":false,"fork":false,"pushed_at":"2025-06-26T14:36:07.000Z","size":339,"stargazers_count":126,"open_issues_count":18,"forks_count":23,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-06-26T15:33:09.725Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeepLcom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-08-29T10:25:51.000Z","updated_at":"2025-06-26T14:36:11.000Z","dependencies_parsed_at":"2023-02-01T03:30:51.826Z","dependency_job_id":"62073b6d-be40-4480-baee-887e485d07c3","html_url":"https://github.com/DeepLcom/deepl-java","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/DeepLcom/deepl-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeepLcom","download_url":"https://codeload.github.com/DeepLcom/deepl-java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeepLcom%2Fdeepl-java/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262172482,"owners_count":23270023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-04T17:30:42.073Z","updated_at":"2025-06-27T01:31:38.430Z","avatar_url":"https://github.com/DeepLcom.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DeepL Java Library\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.deepl.api/deepl-java.svg)](https://mvnrepository.com/artifact/com.deepl.api/deepl-java)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blueviolet.svg)](https://github.com/DeepLcom/deepl-java/blob/main/LICENSE)\n\nThe [DeepL API][api-docs] is a language AI API that allows other computer programs\nto send texts and documents to DeepL's servers and receive high-quality\ntranslations and improvements to the text. This opens a whole universe of\nopportunities for developers: any translation product you can imagine can now\nbe built on top of DeepL's best-in-class translation technology.\n\nThe DeepL Java library offers a convenient way for applications written in Java\nto interact with the DeepL API. We intend to support all API functions with the\nlibrary, though support for new features may be added to the library after\nthey’re added to the API.\n\n## Getting an authentication key\n\nTo use the DeepL Java Library, you'll need an API authentication key. To get a\nkey, [please create an account here][create-account]. With a DeepL API Free\naccount you can consume up to 500,000 characters/month for free.\n\n## Requirements\n\nJava 1.8 or later.\n\n## Installation\n\n### Gradle users\n\nAdd this dependency to your project's build file:\n\n```\nimplementation \"com.deepl.api:deepl-java:1.10.1\"\n```\n\n### Maven users\n\nAdd this dependency to your project's POM:\n\n```\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.deepl.api\u003c/groupId\u003e\n  \u003cartifactId\u003edeepl-java\u003c/artifactId\u003e\n  \u003cversion\u003e1.10.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\nImport the package and construct a `DeepLClient`. The first argument is a string\ncontaining your API authentication key as found in your\n[DeepL Pro Account][pro-account].\n\nBe careful not to expose your key, for example when sharing source code.\n\n```java\nimport com.deepl.api.*;\n\nclass Example {\n    DeepLClient client;\n\n    public Example() throws Exception {\n        String authKey = \"f63c02c5-f056-...\";  // Replace with your key\n        client = new DeepLClient(authKey);\n        TextResult result =\n                client.translateText(\"Hello, world!\", null, \"fr\");\n        System.out.println(result.getText()); // \"Bonjour, le monde !\"\n    }\n}\n```\n\nThis example is for demonstration purposes only. In production code, the\nauthentication key should not be hard-coded, but instead fetched from a\nconfiguration file or environment variable.\n\n`DeepLClient` accepts additional options, see [Configuration](#configuration)\nfor more information.\n\n### Translating text\n\nTo translate text, call `translateText()`. The first argument is a string\ncontaining the text you want to translate, or an iterable of strings if you want\nto translate multiple texts.\n\n`sourceLang` and `targetLang` specify the source and target language codes\nrespectively. The `sourceLang` is optional, if it is `null` the source language\nwill be auto-detected.\n\nLanguage codes are **case-insensitive** strings according to ISO 639-1, for\nexample `'de'`, `'fr'`, `'ja''`. Some target languages also include the regional\nvariant according to ISO 3166-1, for example `'en-US'`, or `'pt-BR'`. The full\nlist of supported languages is in the [API documentation][api-docs-lang-list].\n\nThere are additional optional arguments to control translation, see\n[Text translation options](#text-translation-options) below.\n\n`translateText()` returns a `TextResult`, or a List of `TextResult`s\ncorresponding to your input text(s). `TextResult` has the following accessors:\n- `getText()` returns the translated text,\n- `getDetectedSourceLanguage()` returns the detected source language code,\n- `getBilledCharacters()` returns the number of characters billed for the text, and\n- `getModelTypeUsed()` returns the model type used for the translation.\n\n```java\nclass Example {  // Continuing class Example from above\n    public void textTranslationExamples() throws Exception {\n        // Translate text into a target language, in this case, French:\n        TextResult result =\n                client.translateText(\"Hello, world!\", null, \"fr\");\n        System.out.println(result.getText()); // \"Bonjour, le monde !\"\n\n        // Translate multiple texts into British English\n        List\u003cTextResult\u003e results =\n                client.translateText(List.of(\"お元気ですか？\", \"¿Cómo estás?\"),\n                                         null,\n                                         \"en-GB\");\n        System.out.println(results.get(0).getText()); // \"How are you?\"\n        System.out.println(results.get(0).getDetectedSourceLanguage()); // \"ja\" the language code for Japanese\n        System.out.println(results.get(0).getBilledCharacters()); // 7 - the number of characters in the source text \"お元気ですか？\"\n        System.out.println(results.get(1).getText()); // \"How are you?\"\n        System.out.println(results.get(1).getDetectedSourceLanguage()); // \"es\" the language code for Spanish\n        System.out.println(results.get(1).getBilledCharacters()); // 12 - the number of characters in the source text \"¿Cómo estás?\"\n\n        // Translate into German with less and more Formality:\n        System.out.println(client.translateText(\"How are you?\",\n                                                    null,\n                                                    \"de\",\n                                                    new TextTranslationOptions().setFormality(\n                                                            Formality.Less)).getText());  // 'Wie geht es dir?'\n        System.out.println(client.translateText(\"How are you?\",\n                                                    null,\n                                                    \"de\",\n                                                    new TextTranslationOptions().setFormality(\n                                                            Formality.More)).getText());  // 'Wie geht es Ihnen?'\n    }\n}\n```\n\n#### Text translation options\n\nIn addition to the input text(s) argument, a `translateText()` overload accepts\na `TextTranslationOptions`, with the following setters:\n\n- `setSentenceSplittingMode()`: specify how input text should be split into\n  sentences, default: `'on'`.\n    - `SentenceSplittingMode.All`: input text will be split into sentences using\n      both newlines and punctuation.\n    - `SentenceSplittingMode.Off`: input text will not be split into sentences.\n      Use this for applications where each input text contains only one\n      sentence.\n    - `SentenceSplittingMode.NoNewlines`: input text will be split into\n      sentences using punctuation but not newlines.\n- `setPreserveFormatting()`: controls automatic-formatting-correction. Set to\n  `True` to prevent automatic-correction of formatting, default: `false`.\n- `setFormality()`: controls whether translations should lean toward informal or\n  formal language. This option is only available for some target languages, see\n  [Listing available languages](#listing-available-languages).\n    - `Formality.Less`: use informal language.\n    - `Formality.More`: use formal, more polite language.\n- `setGlossary()`: specifies a glossary to use with translation, as a string\n  containing the glossary ID, or a `GlossaryInfo`/`MultilingualGlossaryInfo` \n  object (this object is returned by glossary lookup functions, for example \n  `listGlossaries()` or `listMultilingualGlossaries()`).\n    - `setGlossaryId()` is also available for backward-compatibility, accepting\n      a string containing the glossary ID.\n- `setContext()`: specifies additional context to influence translations, that is not\n  translated itself. Characters in the `context` parameter are not counted toward billing.  \n  See the [API documentation][api-docs-context-param] for more information and\n  example usage.\n- `model_type`: specifies the type of translation model to use, options are:\n  - `'quality_optimized'`: use a translation model that maximizes translation quality,\n    at the cost of response time. This option may be unavailable for some language pairs.\n  - `'prefer_quality_optimized'`: use the highest-quality translation model for the given\n    language pair.\n  - `'latency_optimized'`: use a translation model that minimizes response time, at the\n    cost of translation quality.\n- `setTagHandling()`: type of tags to parse before translation, options are\n  `\"html\"` and `\"xml\"`.\n\nThe following options are only used if `setTagHandling()` is set to `'xml'`:\n\n- `setOutlineDetection()`: specify `false` to disable automatic tag detection,\n  default is `true`.\n- `setSplittingTags()`: list of XML tags that should be used to split text into\n  sentences. Tags may be specified as an array of strings (`['tag1', 'tag2']`),\n  or a comma-separated list of strings (`'tag1,tag2'`). The default is an empty\n  list.\n- `setNonSplittingTags()`: list of XML tags that should not be used to split\n  text into sentences. Format and default are the same as for splitting tags.\n- `setIgnoreTags()`: list of XML tags that containing content that should not be\n  translated. Format and default are the same as for splitting tags.\n\nFor a detailed explanation of the XML handling options, see the\n[API documentation][api-docs-xml-handling].\n\n### Improving text (Write API)\n\nYou can use the Write API to improve or rephrase text. This is implemented in\nthe `rephraseText()` method. The first argument is a string containing the text\nyou want to translate, or a list of strings if you want to translate multiple texts.\n\n`targetLang` optionally specifies the target language, e.g. when you want to change\nthe variant of a text (for example, you can send an english text to the write API and\nuse `targetLang` to turn it into British or American English). Please note that the\nWrite API itself does NOT translate. If you wish to translate and improve a text, you\nwill need to make multiple calls in a chain.\n\nLanguage codes are the same as for translating text.\n\nExample call:\n\n```java\nWriteResult result = client.rephraseText(\"A rainbouw has seven colours.\", \"EN-US\", null);\nSystem.out.println(result.getText);\n```\n\nAdditionally, you can optionally specify a style OR a tone (not both at once) that the\nimprovement should be in. The following styles are supported (`default` will be used if\nnothing is selected):\n\n- `academic`\n- `business`\n- `casual`\n- `default`\n- `simple`\n\nThe following tones are supported (`default` will be used if nothing is selected):\n\n- `confident`\n- `default`\n- `diplomatic`\n- `enthusiastic`\n- `friendly`\n\nYou can also prefix any non-default style or tone with `prefer_` (`prefer_academic`, etc.),\nin which case the style/tone will only be applied if the language supports it. If you do not\nuse `prefer_`, requests with `targetLang`s or detected languages that do not support\nstyles and tones will fail. The current list of supported languages can be found in our\n[API documentation][api-docs]. We plan to also expose this information via an API endpoint\nin the future.\n\nYou can use the predefined constants in the library to use a style:\n\n```java\nTextRephraseOptions options = (new TextRephraseOptions()).setWritingStyle(WritingStyle.Business.getValue());\nWriteResult result = client.rephraseText(\"A rainbouw has seven colours.\", \"EN-US\", options);\nSystem.out.println(result.getText);\n```\n\n### Translating documents\n\nTo translate documents, call `translateDocument()` File objects. The first and\nsecond arguments correspond to the input and output files respectively.\n\nJust as for the `translateText()` function, the `sourceLang` and\n`targetLang` arguments specify the source and target language codes.\n\nThere are additional optional arguments to control translation, see\n[Document translation options](#document-translation-options) below.\n\n```java\nclass Example {  // Continuing class Example from above\n    public void documentTranslationExamples() throws Exception {\n        // Translate a formal document from English to German\n        File inputFile = new File(\"/path/to/Instruction Manual.docx\");\n        File outputFile = new File(\"/path/to/Bedienungsanleitung.docx\");\n        try {\n            client.translateDocument(inputFile, outputFile, \"en\", \"de\");\n        } catch (DocumentTranslationException exception) {\n            // If an error occurs during document translation after the document was\n            // already uploaded, a DocumentTranslationException is thrown. The\n            // document_handle property contains the document handle that may be used to\n            // later retrieve the document from the server, or contact DeepL support.\n            DocumentHandle handle = exception.getHandle();\n            System.out.printf(\n                    \"Error after uploading %s, document handle: id: %s key: %s\",\n                    exception.getMessage(),\n                    handle.getDocumentId(),\n                    handle.getDocumentKey());\n        }\n    }\n}\n```\n\n`translateDocument()` is a convenience function that wraps multiple API calls:\nuploading, polling status until the translation is complete, and downloading. If\nyour application needs to execute these steps individually, you can instead use\nthe following functions directly:\n\n- `translateDocumentUpload()`,\n- `translateDocumentGetStatus()` (or\n  `translateDocumentWaitUntilDone()`), and\n- `translateDocumentDownload()`\n\n#### Document translation options\n\nIn addition to the input file, output file, `sourceLang` and `targetLang`\narguments, `translateDocument()` accepts an optional\n`DocumentTranslationOptions`, with the following setters:\n\n- `setFormality()`: same as\n  in [Text translation options](#text-translation-options).\n- `setGlossary()`: same as\n  in [Text translation options](#text-translation-options).\n- `setGlossaryId()`: same as\n  in [Text translation options](#text-translation-options).\n\n### Glossaries\n\nGlossaries allow you to customize your translations using user-defined terms.\nMultiple glossaries can be stored with your account, each with a user-specified\nname and a uniquely-assigned ID.\n\n### v2 versus v3 glossary APIs\n\nThe newest version of the glossary APIs are the `/v3` endpoints, allowing both\nediting functionality plus support for multilingual glossaries. New methods and\nobjects have been created to support interacting with these new glossaries.\nDue to this new functionality, users are recommended to utilize these\nmultilingual glossary methods. However, to continue using the `v2` glossary API\nendpoints, please continue to use the existing endpoints in the `translator.java`\n(e.g. `createGlossary()`, `getGlossary()`, etc).\n\nTo migrate to use the new multilingual glossary methods from the current\nmonolingual glossary methods, please refer to\n[this migration guide](upgrading_to_multilingual_glossaries.md).\n\nThe following sections describe how to interact with multilingual glossaries\nusing the new functionality:\n\n#### Creating a glossary\n\nYou can create a glossary with `createMultilingualGlossary()` by passing your\ndesired glossary name, and a `GlossaryEntries` object specifying the terms to\nstore in the glossary.\n\nEach glossary contains a list of dictionaries, where each dictionary applies to a single source-target language pair. Note: Glossaries\nare only supported for some language pairs, see\n[Listing available glossary languages](#listing-available-glossary-languages)\nfor more information.\n\nIf successful, the glossary is created and stored with your DeepL account, and\na `MultilingualGlossaryInfo` object is returned including the ID, name, \nlanguages and entry count.\n\n```java\nclass Example {  // Continuing class Example from above\n    public void createGlossaryExample() throws Exception {\n        // Create an English to German glossary with two terms:\n        GlossaryEntries entries = new GlossaryEntries() {{\n            put(\"artist\", \"Maler\");\n            put(\"prize\", \"Gewinn\");\n        }};\n        MultilingualGlossaryDictionaryEntries myGlossaryDicts = \n                Arrays.asList(new MultilingualGlossaryDictionaryEntries(\n                                \"en\",\n                                \"de\",\n                                entries\n                              ));\n        MultilingualGlossaryInfo myGlossary =\n                client.createGlossary(\"My glossary\", myGlossaryDicts);\n\n        System.out.printf(\"Created '%s' (%s) containing %d dictionary from %s-\u003e%s with %d entries\\n\",\n                          myGlossary.getName(),\n                          myGlossary.getGlossaryId(),\n                          myGlossary.getDictionaries().length,\n                          myGlossary.getSourceLang(),\n                          myGlossary.getTargetLang(),\n                          myGlossary.getEntryCount());\n        // Example: Created 'My glossary' (559192ed-8e23-...) containing 1 \n        // dictionary from en-\u003ede containing 2 entries\n    }\n}\n```\n\nTo construct the GlossaryEntries, you can insert entries using typical Map \nfunctions like `put()`. The `fromTsv()` function allows creating GlossaryEntries\nfrom TSV data.\n\nYou can also create a glossary using a glossary downloaded from the DeepL\nwebsite by using `createMultilingualGlossaryFromCsv()` with either a CSV file,\nor a string containing the CSV data:\n\n```java\nclass Example {  // Continuing class Example from above\n    public createGlossaryFromCsvExample() throws Exception {\n        File csvFile = new File(\"/path/to/glossary_file.csv\");\n        MultilingualGlossaryInfo myGlossary =\n                client.createMultilingualGlossaryFromCsv(\"My glossary\",\n                                                         \"en\",\n                                                         \"de\",\n                                                         csvFile);\n    }\n}\n```\n\nThe [API documentation][api-docs-csv-format] explains the expected CSV format in\ndetail.\n\n\n#### Getting, listing and deleting stored glossaries\n\nFunctions to get, list, and delete stored glossaries are also provided:\n\n- `getMultilingualGlossary()` takes a glossary ID and returns a\n  `MultilingualGlossaryInfo` object for a stored glossary, or raises an\n  exception if no such glossary is found.\n- `listMultilingualGlossaries()` returns a list of `MultilingualGlossaryInfo`\n  objects corresponding to all of your stored glossaries.\n- `deleteMultilingualGlossary()` takes a glossary ID or\n  `MultilingualGlossaryInfo` object and deletes the stored glossary from the\n  server, or raises an exception if no such glossary is found.\n- `deleteMultilingualGlossaryDictionary()` takes a glossary ID or\n  `MultilingualGlossaryInfo` object to identify the glossary. Additionally\n  takes in a source and target language or a\n  `MultilingualGlossaryDictionaryInfo` object and deletes the stored dictionary\n  from the server, or raises an exception if no such glossary dictionary is\n  found.\n\n```java\nclass Example {  // Continuing class Example from above\n    public getListDeleteGlossaryExamples() throws Exception {\n        // Retrieve a stored glossary using the ID\n        String glossaryId = \"559192ed-8e23-...\";\n        MultilingualGlossaryInfo myGlossary = \n          client.getMultilingualGlossary(glossaryId);\n\n        client.deleteMultilingualGlossaryDictionary(glossaryId, \n                                                    myGlossary.getDictionaries()[0]);\n\n        // Find and delete glossaries named 'Old glossary'\n        List\u003cMultilingualGlossaryInfo\u003e glossaries = \n          client.listMultilingualGlossaries();\n        for (MultilingualGlossaryInfo glossary : glossaries) {\n            if (glossary.getName() == \"Old glossary\") {\n                client.deleteMultilingualGlossary(glossary);\n            }\n        }\n    }\n}\n```\n\n#### Listing entries in a stored glossary\n\nThe `MultilingualGlossaryDictionaryInfo` object does not contain the glossary\nentries, but instead only the number of entries in the `entry_count` property.\n\nTo list the entries contained within a stored glossary, use\n`getMultilingualGlossaryDictionaryEntries()` providing either the \n`MultilingualGlossaryInfo` object or glossary ID and either a \n`MultilingualGlossaryDictionaryInfo` or source and target language pair:\n\n```java\nclass Example {  // Continuing class Example from above\n  public getGlossaryEntriesExample() throws Exception {\n      List\u003cMultilingualGlossaryDictionaryInfo\u003e glossaryDicts = \n        client.getMultilingualGlossaryDictionaryEntries(myGlossary, \"en\", \"de\");\n      \n      for (Map.Entry\u003cString, String\u003e entry : glossaryDicts.getDictionaries()[0].getEntries().entrySet()) {\n        System.out.println(entry.getKey() + \":\" + entry.getValue());\n      }\n      // prints:\n      //   artist:Maler\n      //   prize:Gewinn\n  }\n}\n```\n\n#### Editing a glossary\n\nFunctions to edit stored glossaries are also provided:\n\n- `updateMultilingualGlossaryDictionary()` takes a glossary ID or `MultilingualGlossaryInfo`\n  object, plus a source language, target language, and a dictionary of entries.\n  It will then either update the list of entries for that dictionary (either\n  inserting new entires or replacing the target phrase for any existing\n  entries) or will insert a new glossary dictionary if that language pair is\n  not currently in the stored glossary.\n- `replaceMultilingualGlossaryDictionary()` takes a glossary ID or `MultilingualGlossaryInfo`\n  object, plus a source language, target language, and a dictionary of entries.\n  It will then either set the entries to the parameter value, completely\n  replacing any pre-existing entries for that language pair.\n- `updateMultilingualGlossaryName()` takes a glossary ID or `MultilingualGlossaryInfo`\n  object, plus the new name of the glossary.\n\n```java\n// Update glossary dictionary\nclass Example {  // Continuing class Example from above\n  public updateGlossaryEntriesExample() throws Exception {\n    GlossaryEntries entries = new GlossaryEntries() {{\n              put(\"artist\", \"Maler\");\n              put(\"hello\", \"guten tag\");\n          }};\n    List\u003cMultilingualGlossaryDictionaryEntries\u003e dictionaries = \n      Arrays.asList(new MultilingualGlossaryDictionaryEntries(\"EN\", \"DE\", entries));\n    MultilingualGlossaryInfo myGlossary = client.createMultilingualGlossary(\n        \"My glossary\",\n        dictionaries\n    );\n\n    GlossaryEntries newEntries = new GlossaryEntries() {{\n              put(\"hello\", \"hallo\");\n              put(\"prize\", \"Gewinn\");\n          }};\n\n    MultilingualGlossaryDictionaryEntries glossaryDict = \n      new MultilingualGlossaryDictionaryEntries(\"EN\", \"DE\", newEntries);\n\n    MultilingualGlossaryInfo updatedGlossary = \n      client.updateMultilingualGlossaryDictionary(myGlossary, glossaryDict);\n\n    MultilingualGlossaryInfo entriesResponse = \n      client.getMultilingualGlossaryDictionaryEntries(myGlossary, \"EN\", \"DE\");\n\n    for (Map.Entry\u003cString, String\u003e entry : glossaryDicts.getDictionaries()[0].getEntries().entrySet()) {\n      System.out.println(entry.getKey() + \":\" + entry.getValue());\n    }\n    \n    // prints:\n    //   artist:Maler\n    //   hello:hallo\n    //   prize:Gewinn\n  }\n\n  // Update a glossary dictionary from CSV\n  public updateGlossaryEntriesFromCsvExample() throws Exception {\n    File csvFile = new File(\"/path/to/glossary_file.csv\");\n    String glossaryId = \"559192ed-8e23-...\";\n    MultilingualGlossaryInfo myGlossary =\n      client.createMultilingualGlossaryDictionaryFromCsv(glossaryId,\n                                                        \"en\",\n                                                        \"de\",\n                                                        csvFile);\n  }\n\n\n  // Update a glossary name\n  public void updateGlossaryNameExample() throws Exception {\n    String glossaryId = \"559192ed-8e23-...\";\n    MultilingualGlossaryInfo myGlossary =\n      client.updateMultilingualName(glossaryId, \"My new glossary name\");\n    System.out.println(myGlossary.getName()); // 'My new glossary name'\n  }\n\n  // Replace a glossary dictionary\n  public void replaceGlossaryEntriesExample() throws Exception {\n    GlossaryEntries entries = new GlossaryEntries() {{\n              put(\"artist\", \"Maler\");\n              put(\"hello\", \"guten tag\");\n          }};\n    List\u003cMultilingualGlossaryDictionaryEntries\u003e dictionaries = \n      Arrays.asList(new MultilingualGlossaryDictionaryEntries(\"EN\", \"DE\", entries));\n    MultilingualGlossaryInfo myGlossary = client.createMultilingualGlossary(\n        \"My glossary\",\n        dictionaries\n    );\n\n    GlossaryEntries newEntries = new GlossaryEntries() {{\n              put(\"goodbye\", \"Auf Weidersehen\");\n          }};\n\n    MultilingualGlossaryDictionaryEntries glossaryDict = \n      new MultilingualGlossaryDictionaryEntries(\"EN\", \"DE\", newEntries);\n\n    MultilingualGlossaryInfo updatedGlossary = \n      client.replaceMultilingualGlossaryDictionary(myGlossary, glossaryDict);\n\n    MultilingualGlossaryInfo entriesResponse = \n      client.getMultilingualGlossaryDictionaryEntries(myGlossary, \"EN\", \"DE\");\n\n    for (Map.Entry\u003cString, String\u003e entry : glossaryDicts.getDictionaries()[0].getEntries().entrySet()) {\n      System.out.println(entry.getKey() + \":\" + entry.getValue());\n    }\n    \n    // prints:\n    //   goodbye:Auf Weidersehen\n  }\n\n  // Replace a glossary dictionary from CSV\n  public void replaceGlossaryEntriesFromCsvExample() throws Exception {\n    File csvFile = new File(\"/path/to/glossary_file.csv\");\n    String glossaryId = \"559192ed-8e23-...\";\n    MultilingualGlossaryInfo myGlossary =\n      client.replaceMultilingualGlossaryDictionaryFromCsv(glossaryId,\n                                                          \"en\",\n                                                          \"de\",\n                                                          csvFile);\n    MultilingualGlossaryInfo entriesResponse = \n      client.getMultilingualGlossaryDictionaryEntries(myGlossary, \"EN\", \"DE\");\n  }\n}\n```\n\n#### Using a stored glossary\n\nYou can use a stored glossary for text translation by setting the `glossary`\nargument to either the glossary ID or `MultilingualGlossaryInfo` object. You must also\nspecify the `source_lang` argument (it is required when using a glossary):\n\n```java\nclass Example {  // Continuing class Example from above\n    public boid usingGlossaryExample() throws Exception {\n        String text = \"The artist was awarded a prize.\";\n        TextTranslationOptions options =\n                new TextTranslationOptions().setGlossary(my_glossary);\n        TextResult resultWithGlossary =\n                client.translateText(text, \"en\", \"de\", options);\n        System.out.println(resultWithGlossary.getText()); // \"Der Maler wurde mit einem Gewinn ausgezeichnet.\"\n\n        // For comparison, the result without a glossary:\n        TextResult resultWithoutGlossary =\n                client.translateText(text, \"en\", \"de\");\n        System.out.println(resultWithoutGlossary.getText()); // \"Der Künstler wurde mit einem Preis ausgezeichnet.\"\n    }\n}\n```\n\nUsing a stored glossary for document translation is the same: set the `glossary`\nargument and specify the `source_lang` argument:\n\n```java\nclass Example {  // Continuing class Example from above\n    public boid getListDeleteGlossaryExamples() throws Exception {\n        String glossaryId = \"559192ed-8e23-...\";\n        DocumentTranslationOptions options =\n                new DocumentTranslationOptions().setGlossary(glossaryId);\n\n        File inputFile = new File(\"/path/to/Instruction Manual.docx\");\n        File outputFile = new File(\"/path/to/Bedienungsanleitung.docx\");\n        client.translateDocument(inputFile,\n                                     outputFile,\n                                     \"en\",\n                                     \"de\",\n                                     options);\n    }\n}\n```\n\nThe `translateDocument()` and `translateDocumentUpload()` functions both\nsupport the `glossary` argument.\n\n### Checking account usage\n\nTo check account usage, use the `getUsage()` function.\n\nThe returned `Usage` object contains three usage subtypes: `character`,\n`document` and `teamDocument`. Depending on your account type, some usage\nsubtypes may be `null`. For API accounts:\n\n- `usage.character` is non-`null`,\n- `usage.document` and `usage.teamDocument` are `null`.\n\nEach usage subtype (if valid) has `count` and `limit` properties giving the\namount used and maximum amount respectively, and the `limit_reached` property\nthat checks if the usage has reached the limit. The top level `Usage` object has\nthe `any_limit_reached` property to check all usage subtypes.\n\n```java\nclass Example {  // Continuing class Example from above\n    public void getUsageExample() throws Exception {\n        Usage usage = client.getUsage();\n        if (usage.anyLimitReached()) {\n            System.out.println(\"Translation limit reached.\");\n        }\n        if (usage.getCharacter() != null) {\n            System.out.printf(\"Character usage: %d of %d%n\",\n                              usage.getCharacter().getCount(),\n                              usage.getCharacter().getLimit());\n        }\n        if (usage.getDocument() != null) {\n            System.out.printf(\"Document usage: %d of %d%n\",\n                              usage.getDocument().getCount(),\n                              usage.getDocument().getLimit());\n        }\n    }\n}\n```\n\n### Listing available languages\n\nYou can request the list of languages supported by DeepL for text and documents\nusing the `getSourceLanguages()` and `getTargetLanguages()` functions. They both\nreturn a list of `Language` objects.\n\nThe `name` property gives the name of the language in English, and the `code`\nproperty gives the language code. The `supportsFormality` property only appears\nfor target languages, and indicates whether the target language supports the\noptional `formality` parameter.\n\n```java\nclass Example {  // Continuing class Example from above\n    public void getLanguagesExample() throws Exception {\n        List\u003cLanguage\u003e sourceLanguages = client.getSourceLanguages();\n        List\u003cLanguage\u003e targetLanguages = client.getTargetLanguages();\n        System.out.println(\"Source languages:\");\n        for (Language language : sourceLanguages) {\n            System.out.printf(\"%s (%s)%n\",\n                              language.getName(),\n                              language.getCode()); // Example: \"German (de)\"\n        }\n\n        System.out.println(\"Target languages:\");\n        for (Language language : targetLanguages) {\n            if (language.getSupportsFormality()) {\n                System.out.printf(\"%s (%s) supports formality%n\",\n                                  language.getName(),\n                                  language.getCode()); // Example: \"Italian (it) supports formality\"\n\n            } else {\n                System.out.printf(\"%s (%s)%n\",\n                                  language.getName(),\n                                  language.getCode()); // Example: \"Lithuanian (lt)\"\n            }\n        }\n    }\n}\n```\n\n#### Listing available glossary languages\n\nGlossaries are supported for a subset of language pairs. To retrieve those\nlanguages use the `getGlossaryLanguages()` function, which returns an array\nof `GlossaryLanguagePair` objects. Use the `getSourceLanguage()` and\n`getTargetLanguage()` functions to check the pair of language codes supported.\n\n```java\nclass Example {  // Continuing class Example from above\n    public void getGlossaryLanguagesExample() throws Exception {\n        List\u003cGlossaryLanguagePair\u003e glossaryLanguages =\n                client.getGlossaryLanguages();\n        for (GlossaryLanguagePair glossaryLanguage : glossaryLanguages) {\n            System.out.printf(\"%s to %s\\n\",\n                              glossaryLanguage.getSourceLanguage(),\n                              glossaryLanguage.getTargetLanguage());\n            // Example: \"en to de\", \"de to en\", etc.\n        }\n    }\n}\n```\n\nYou can also find the list of supported glossary language pairs in the\n[API documentation][api-docs-glossary-lang-list].\n\nNote that glossaries work for all target regional-variants: a glossary for the\ntarget language English (`\"en\"`) supports translations to both American English\n(`\"en-US\"`) and British English (`\"en-GB\"`).\n\n### Exceptions\n\nAll module functions may raise `DeepLException` or one of its subclasses. If\ninvalid arguments are provided, they may raise the standard exceptions\n`IllegalArgumentException`.\n\n### Writing a Plugin\n\nIf you use this library in an application, please identify the application with\n`DeepLClientOptions.setAppInfo()`, which takes the name and version of the app:\n\n```java\nclass Example {  // Continuing class Example from above\n    public void configurationExample() throws Exception {\n        DeepLClientOptions options =\n                new DeepLClientOptions().setAppInfo(\"my-java-translation-plugin\", \"1.2.3\");\n        DeepLClient client = new DeepLClient(authKey, options);\n    }\n}\n```\n\nThis information is passed along when the library makes calls to the DeepL API.\nBoth name and version are required. Please note that setting the `User-Agent` header\nvia `DeepLClientOptions.setHeaders()` will override this setting, if you need to use this,\nplease manually identify your Application in the `User-Agent` header.\n\n### Configuration\n\nThe `DeepLClient` constructor accepts `DeepLClientOptions` as a second argument,\nfor example:\n\n```java\nclass Example {  // Continuing class Example from above\n    public void configurationExample() throws Exception {\n        DeepLClientOptions options =\n                new DeepLClientOptions().setMaxRetries(1).setTimeout(Duration.ofSeconds(\n                        1));\n        DeepLClient client = new DeepLClient(authKey, options);\n    }\n}\n```\n\nThe available options setters are:\n\n- `setMaxRetries()`: maximum number of failed HTTP requests to retry, the\n  default is 5. Note: only failures due to transient conditions are retried e.g.\n  timeouts or temporary server overload.\n- `setTimeout()`: connection timeout for each HTTP request.\n- `setProxy()`: provide details about a proxy to use for all HTTP requests to\n  DeepL.\n- `setHeaders()`: additional HTTP headers to attach to all requests.\n- `setServerUrl()`: base URL for DeepL API, may be overridden for testing\n  purposes. By default, the correct DeepL API (Free or Pro) is automatically\n  selected.\n- `setApiVersion()`: Version of the DeepL API, may be overridden to use e.g.\n  the v1 API. By default, the most recent API version is automatically selected.\n  Please note: The v1 API does not support all features of the API, e.g.\n  document translation or rephrase.\n\n#### Anonymous platform information\n\nBy default, we send some basic information about the platform the client library is running on with each request, see [here for an explanation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). This data is completely anonymous and only used to improve our product, not track any individual users. If you do not wish to send this data, you can opt-out when creating your `DeepLClient` object by calling the `setSendPlatformInfo()` setter on the `DeepLClientOptions` like so:\n\n```java\nclass Example {  // Continuing class Example from above\n    public void configurationExample() throws Exception {\n        DeepLClientOptions options =\n                new DeepLClientOptions().setSendPlatformInfo(false);\n        DeepLClient client = new DeepLClient(authKey, options);\n    }\n}\n```\n\nYou can also customize the `User-Agent` header by setting its value explicitly in the `DeepLClientOptions` object via the header field. Example:\n\n```java\nclass Example {  // Continuing class Example from above\n    public void configurationExample() throws Exception {\n        Map\u003cString, String\u003e headers = new HashMap\u003c\u003e();\n        headers.put(\"User-Agent\", \"my custom user agent\");\n        DeepLClientOptions options =\n                new DeepLClientOptions().setHeaders(headers);\n        DeepLClient client = new DeepLClient(authKey, options);\n    }\n}\n```\n\n## Issues\n\nIf you experience problems using the library, or would like to request a new\nfeature, please open an [issue][issues].\n\n## Development\n\nWe welcome Pull Requests, please read the\n[contributing guidelines](CONTRIBUTING.md).\n\n### Tests\n\nExecute the tests using `./gradlew test`. The tests communicate with the DeepL\nAPI using the auth key defined by the `DEEPL_AUTH_KEY` environment variable.\n\nBe aware that the tests make DeepL API requests that contribute toward your API\nusage.\n\nThe test suite may instead be configured to communicate with the mock-server\nprovided by [deepl-mock][deepl-mock]. Although most test cases work for either,\nsome test cases work only with the DeepL API or the mock-server and will be\notherwise skipped. The test cases that require the mock-server trigger server\nerrors and test the client error-handling. To execute the tests using\ndeepl-mock, run it in another terminal while executing the tests. Execute the\ntests using `./gradlew test` with the `DEEPL_MOCK_SERVER_PORT` and\n`DEEPL_SERVER_URL` environment variables defined referring to the mock-server.\n\n[api-docs]: https://www.deepl.com/docs-api?utm_source=github\u0026utm_medium=github-java-readme\n\n[api-docs-context-param]: https://www.deepl.com/docs-api/translating-text/?utm_source=github\u0026utm_medium=github-java-readme\n\n[api-docs-csv-format]: https://www.deepl.com/docs-api/managing-glossaries/supported-glossary-formats/?utm_source=github\u0026utm_medium=github-java-readme\n\n[api-docs-xml-handling]: https://www.deepl.com/docs-api/handling-xml/?utm_source=github\u0026utm_medium=github-java-readme\n\n[api-docs-lang-list]: https://www.deepl.com/docs-api/translating-text/?utm_source=github\u0026utm_medium=github-java-readme\n\n[api-docs-glossary-lang-list]: https://www.deepl.com/docs-api/managing-glossaries/?utm_source=github\u0026utm_medium=github-java-readme\n\n[create-account]: https://www.deepl.com/pro?utm_source=github\u0026utm_medium=github-java-readme#developer\n\n[deepl-mock]: https://www.github.com/DeepLcom/deepl-mock\n\n[issues]: https://www.github.com/DeepLcom/deepl-java/issues\n\n[pro-account]: https://www.deepl.com/pro-account/?utm_source=github\u0026utm_medium=github-java-readme\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeeplcom%2Fdeepl-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeeplcom%2Fdeepl-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeeplcom%2Fdeepl-java/lists"}