{"id":13550696,"url":"https://github.com/komape/deepl_dart","last_synced_at":"2025-04-13T12:27:50.176Z","repository":{"id":41982375,"uuid":"481312072","full_name":"komape/deepl_dart","owner":"komape","description":"Dart library for the DeepL language translation API. ","archived":false,"fork":false,"pushed_at":"2025-03-02T15:17:20.000Z","size":110,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T12:27:38.393Z","etag":null,"topics":["dart","deepl","sdk","translation"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/deepl_dart","language":"Dart","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/komape.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-13T17:29:37.000Z","updated_at":"2025-03-02T15:13:04.000Z","dependencies_parsed_at":"2024-03-16T23:56:30.836Z","dependency_job_id":"6b8e88be-c0b8-4445-9d9c-f1f550504fd8","html_url":"https://github.com/komape/deepl_dart","commit_stats":{"total_commits":58,"total_committers":2,"mean_commits":29.0,"dds":0.06896551724137934,"last_synced_commit":"cc564f3cadf9d4cc617d526825725abb20776300"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komape%2Fdeepl_dart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komape%2Fdeepl_dart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komape%2Fdeepl_dart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komape%2Fdeepl_dart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/komape","download_url":"https://codeload.github.com/komape/deepl_dart/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248713528,"owners_count":21149713,"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":["dart","deepl","sdk","translation"],"created_at":"2024-08-01T12:01:36.328Z","updated_at":"2025-04-13T12:27:50.165Z","avatar_url":"https://github.com/komape.png","language":"Dart","funding_links":[],"categories":["Dart","Awesome DeepL"],"sub_categories":["Client Libraries \u0026 SDKs"],"readme":"# [deepl_dart](https://pub.dev/packages/deepl_dart)\n\n[![Dart Analyze \u0026 Test](https://github.com/komape/deepl_dart/actions/workflows/dart_analyze_test.yml/badge.svg)](https://github.com/komape/deepl_dart/actions/workflows/dart_analyze_test.yml) [![codecov](https://codecov.io/gh/komape/deepl_dart/branch/master/graph/badge.svg?token=RF7B8BPD77)](https://codecov.io/gh/komape/deepl_dart)\n\n\u003e ⚠️ Prior to version 2.0.0 there was only one `Translator` object which combined the functionality of translation, glossary management and language information. The `Translator` is deprecated and will be removed in a future release. In addition, some methods have been renamed. The old ones still exist, but are deprecated and will be removed in a future release. If you upgrade to version 2.0.0 or higher, please update your code to use the `DeepL` object.\n\n**This package is maintained by volunteers but is not a supported DeepL product and not maintained by DeepL SE. Issues here are answered by maintainers and other community members on GitHub on a best-effort basis.**\n\nThis package is heavily inspired by the [official Node.js Client Library for the DeepL API](https://github.com/DeepLcom/deepl-node):\n\n\u003e The DeepL API is a language translation API that allows other computer programs to send texts and documents to DeepL's servers and receive high-quality translations. This opens a whole universe of opportunities for developers: any translation product you can imagine can now be built on top of DeepL's best-in-class translation technology.\n\u003e\n\u003e The DeepL *[Dart]* library offers a convenient way for applications written for *[Dart and Flutter]* to interact with the DeepL API. We intend to support all API functions with the library, though support for new features may be added to the library after they’re added to the API. *~ DeepL*\n\n- [deepl\\_dart](#deepl_dart)\n  - [Getting an authentication key](#getting-an-authentication-key)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [DeepL Object](#deepl-object)\n    - [Translator](#translator)\n      - [Translate Text](#translate-text)\n      - [Translate Documents](#translate-documents)\n    - [Writer](#writer)\n    - [Glossaries](#glossaries)\n    - [Languages](#languages)\n    - [Usage](#usage-1)\n  - [Additional information](#additional-information)\n\n## Getting an authentication key\n\nTo use the package, you'll need an API authentication key. To get a key, [please create an account here](https://www.deepl.com/pro/change-plan#developer). You can translate up to 500,000characters/month for free.\n\n## Installation\n\nIn the `dependencies`: section of your `pubspec.yaml`, add the following line:\n\n```yaml\ndependencies:\n  deepl_dart: \u003clatest_version\u003e\n```\n\n## Usage\n\nImport the package and construct a `DeepL` object. The required argument `authKey` is a string containing your API authentication key as found in your [DeepL Pro Account](https://www.deepl.com/pro-account/).\n\nBe careful not to expose your key, for example when sharing source code.\n\nAn example using `async/await`:\n\n```dart\nimport 'package:deepl_dart/deepl_dart.dart';\n\nvoid main() async {\n  // Construct Translator\n  DeepL deepl = DeepL(authKey: '\u003cyour_auth_key\u003e');\n\n  // Translate text\n  TextResult result =\n      await deepl.translate.translateText('Hello World', 'de');\n  print(result);\n\n  // Translate list of texts\n  List\u003cTextResult\u003e results =\n      await deepl.translate.translateTextList(['Hello World', 'Hola Mundo'], 'de');\n  print(results);\n}\n```\n\n### DeepL Object\n\nAll requests to the DeepL API go via a `DeepL`. A `auth_key` from DeepL is required to send requests. Pass it via its constructor:\n\n```dart\nDeepL deepl = DeepL(authKey: '\u003cyour_auth_key\u003e');\n```\n\nThis example is for demonstration purposes only. In production code, the authentication key should not be hard-coded, but instead fetched from a configuration file or environment variable.\n\nAdd further arguments to the constructor:\n\n```dart\nDeepL deepl = DeepL(\n    authKey: '\u003cyour_auth_key\u003e',\n    headers: {'My-Header-Key': 'my header value'},\n    serverUrl: 'https://alternative.deepl.api.server.url',\n    maxRetries: 42,\n  );\n```\n\nThe `DeepL` class contains modules for the different functionality of DeepL's API. Here's an overview of the currently available modules which are described in more detail further below.\n\n| Module     | Access             | Description                         |\n| ---------- | ------------------ | ----------------------------------- |\n| Translator | `deepl.translate`  | Translate text and documents.       |\n| Writer     | `deepl.write`      | Rephrase and improve text.          |\n| Glossaries | `deepl.glossaries` | Manage your glossaries.             |\n| Languages  | `deepl.languages`  | Get info about supported languages. |\n\n### Translator\n\n#### Translate Text\n\nThe basic text translation takes one or more texts and a target language to return the translated text. DeepL detects the source language automatically.\n\n```dart\n// Translate a single text\nTextResult result =\n    await deepl.translate.translateTextSingular('Hello World', 'de');\n\n// Translate multiple texts\nList\u003cTextResult\u003e results =\n    await deepl.translate.translateTextList(['Hello World', 'Hola Mundo'], 'de');\n```\n\nOptionally you can pass the source language as well.\n\n```dart\nTextResult result = await deepl.translate\n    .translateTextSingular('Hello World', 'de', sourceLang: 'en');\n```\n\nIf you unsure which languages are supported you can request them.\n\n```dart\n  List\u003cLanguage\u003e sourceLangs = await deepl.languages.getSources();\n  List\u003cLanguage\u003e targetLangs = await deepl.languages.getTargets();\n```\n\nYou can pass a `TranslateTextOptions` object to configure the translation.\n\n```dart\nTextResult result = await deepl.translate.translateTextSingular(\n  'Hello World',\n  'de',\n  options: TranslateTextOptions(\n      splitSentences: 'on',\n      formality: 'less',\n      glossaryId: myGlossary.glossaryId,\n  ),\n);\n```\n\n#### Translate Documents\n\nDeepL also supports the translation of documents. At the moment of writing the following file types are supported:\n\n- `.docx`\n- `.pptx`\n- `.pdf`\n- `.txt`\n\nThe document translation method internally uploads given input file, waits for the translation to finish and downloads the file into the given output file. As well as with the text translation a target language is required.\n\n```dart\nDocumentStatus status = await deepl.translate.translateDocument(\n    File('\u003cinput_file_path\u003e'), File('\u003coutput_file_path\u003e'), 'de');\n```\n\nOptionally you can pass the source language as well.\n\n```dart\nDocumentStatus status = await deepl.translate.translateDocument(\n    File('\u003cinput_file_path\u003e'), File('\u003coutput_file_path\u003e'), 'de',\n    sourceLang: 'en');\n```\n\nYou can pass a `DocumentTranslateOptions` object to configure the translation.\n\n```dart\nDocumentStatus status = await deepl.translate.translateDocument(\n  File('\u003cinput_file_path\u003e'),\n  File('\u003coutput_file_path\u003e'),\n  'de',\n  options: DocumentTranslateOptions(\n    formality: 'less',\n    glossaryId: myGlossary.glossaryId,\n  ),\n);\n```\n\n### Writer\n\nRephrase and improve your text with DeepL Write.\n\n\u003e ⚠ At the moment the text improvement feature is currently only available to DeepL API Pro customers and is not yet available in DeepL API Free.\n\nPass a text that should be improved.\n\n```dart\nTextRephraseResult rephraseResult =\n    await deepl.write.rephraseText('This is a sample sentence to improve.');\n```\n\nYou can also pass multiple texts. Each of the texts may contain multiple sentences. \n\nNote: All texts must be in the same language.\n\n```dart\nList\u003cTextRephraseResult\u003e rephraseResults =\n    await deepl.write.rephraseTextList([\n  'This is a sample sentence to improve.',\n  'This is another sample sentence to improve.',\n]);\n```\n\nUse a `WritingStyle` to change the style of writing. See the `WritingStyle` enum for the available values.\n\n```dart\nTextRephraseResult rephraseResultWithStyle = await deepl.write.rephraseText(\n  'This is a sample sentence to improve.',\n  writingStyle: WritingStyle.academic,\n);\n```\n\nUse a `Tone` to set the tone of the text. See the `Tone` enum for the available values.\n\n```dart\nTextRephraseResult rephraseResultWithTone = await deepl.write.rephraseText(\n  'This is a sample sentence to improve.',\n  tone: Tone.diplomatic,\n);\n```\n\nBe aware that you cannot use `WritingStyle` and `Tone` at the same time.\n\n### Glossaries\n\nDeepL supports glossaries to manage custom translations. To use them you have to create one.\n\n```dart\nGlossaryInfo glossaryInfo = await deepl.glossaries.create(\n  name: 'my glossary',\n  sourceLang: 'en',\n  targetLang: 'de',\n  entries: GlossaryEntries(entries: {\n    'hello': 'hi',\n    'world': 'erde',\n  }),\n);\n```\n\nYou can also upload a glossary downloaded from the DeepL website using `createGlossaryFromCsv()`. Instead of supplying the entries as a GlossaryEntries object, provide the CSV file as a File containing the CSV file content:\n\n```dart\nGlossaryInfo csvGlossaryInfo = await deepl.glossaries.createWithCsvFile(\n  name: 'my glossary',\n  sourceLang: 'en',\n  targetLang: 'de',\n  csvFile: File('\u003ccsv_file_path\u003e'),\n);\n```\n\nThe [API documentation](https://www.deepl.com/docs-api/managing-glossaries/supported-glossary-formats/) explains the expected CSV format in detail.\n\nNot all languages are supported. You can check the possible language pairs.\n\n```dart\n  List\u003cGlossaryLanguagePair\u003e languagePairs =\n      await deepl.glossaries.getLanguagePairs();\n```\n\nOnce you created a glossary you can use it for translations as part of the `TranslateTextOptions` and the `DocumentTranslateOptions` (see above).\n\nTo get all your glossaries or a specific one, you can request them.\n\n```dart\n// List glossaries\nList\u003cGlossaryInfo\u003e glossaryList = await deepl.glossaries.list();\n\n// Get glossary info\nGlossaryInfo glossaryInfo = await deepl.glossaries.get(glossaryInfo.glossaryId);\n```\n\nTo get the entries of a glossary, you have to request them seperately.\n\n```dart\nGlossaryEntries glossaryEntries =\n      await deepl.glossaries.getEntries(glossaryId: '\u003cglossary_info_if\u003e');\n\n// with a glossary info object\nGlossaryEntries glossaryEntries =\n    await deepl.glossaries.getEntries(glossaryInfo: glossaryInfo);\n```\n\nLastly, you can delete a glossary.\n\n```dart\nawait deepl.glossaries.delete(glossaryId: glossaryInfo.glossaryId);\n```\n\n### Languages\n\n### Usage\n\nFind out more about the used translations and your limits.\n\n```dart\nUsage usage = await deepl.getUsage();\n```\n\n## Additional information\n\nFor more information, check out the [official Node.js Client Library for the DeepL API](https://github.com/DeepLcom/deepl-node) and the [DeepL API Docs](https://www.deepl.com/docs-api).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkomape%2Fdeepl_dart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkomape%2Fdeepl_dart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkomape%2Fdeepl_dart/lists"}