{"id":13554244,"url":"https://github.com/chriskonnertz/DeepLy","last_synced_at":"2025-04-03T06:31:18.423Z","repository":{"id":52680302,"uuid":"101918586","full_name":"chriskonnertz/DeepLy","owner":"chriskonnertz","description":"PHP client for the DeepL.com translation API (unofficial)","archived":false,"fork":false,"pushed_at":"2023-12-07T20:08:11.000Z","size":508,"stargazers_count":228,"open_issues_count":2,"forks_count":49,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-10-14T02:25:27.308Z","etag":null,"topics":["ai","api","client","deepl","i18n","language","laravel","library","machine-translation","neural","php","translate","translation","translator"],"latest_commit_sha":null,"homepage":"","language":"PHP","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/chriskonnertz.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":"2017-08-30T19:02:45.000Z","updated_at":"2024-08-08T14:23:54.000Z","dependencies_parsed_at":"2022-08-21T09:20:32.485Z","dependency_job_id":"eb2e2111-3821-4960-bb05-f8af36b6a40a","html_url":"https://github.com/chriskonnertz/DeepLy","commit_stats":{"total_commits":377,"total_committers":1,"mean_commits":377.0,"dds":0.0,"last_synced_commit":"1f32f63bb1cb2e0ecfdde0554e364a27d4103150"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriskonnertz%2FDeepLy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriskonnertz%2FDeepLy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriskonnertz%2FDeepLy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriskonnertz%2FDeepLy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chriskonnertz","download_url":"https://codeload.github.com/chriskonnertz/DeepLy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246947997,"owners_count":20859358,"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":["ai","api","client","deepl","i18n","language","laravel","library","machine-translation","neural","php","translate","translation","translator"],"created_at":"2024-08-01T12:02:43.041Z","updated_at":"2025-04-03T06:31:18.028Z","avatar_url":"https://github.com/chriskonnertz.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"![alt text](https://i.imgur.com/nWPtAKg.png \"DeepLy Logo\")\n\n# DeepLy 2\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/chriskonnertz/DeepLy/php.yml?style=flat-square)](https://github.com/chriskonnertz/DeepLy/actions)\n[![Version](https://img.shields.io/packagist/v/chriskonnertz/DeepLy.svg?style=flat-square)](https://packagist.org/packages/chriskonnertz/deeply)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/chriskonnertz/deeply/master/LICENSE)\n[![Version](https://img.shields.io/packagist/dt/chriskonnertz/deeply?style=flat-square)](https://packagist.org/packages/chriskonnertz/deeply)\n\n[DeepL](https://www.deepl.com/) is a next-generation translation service. \nDeepLy is a dependency-free PHP library that implements a client to interact with the \n[DeepL API](https://www.deepl.com/docs-api) using an API key. \nYou can get an API key for free on their [website](https://www.deepl.com/). \nDeepLy automatically supports both the free and the pro API.\nFor interactive demo scripts take a look at the [demos folder](demos).\n\n## Installation\n\nThis library requires PHP 8.0 or higher and the cURL extension. Install DeepLy trough [Composer](https://getcomposer.org/):\n\n```\ncomposer require chriskonnertz/deeply\n```\n\n## Examples\n\n```php\n$deepLy = new ChrisKonnertz\\DeepLy\\DeepLy('your-api-key');\n\n$translatedText = $deepLy-\u003etranslate('Hello world!', 'DE');\n    \necho $translatedText; // Prints \"Hallo Welt!\"\n```\n\n\u003e 💡 An interactive PHP demo script is included. It is located at [demos/demo_translate.php](demos/demo_translate.php).\n\n### Sophisticated Example\n\n```php\n$deepLy = new ChrisKonnertz\\DeepLy\\DeepLy('your-api-key');\n\ntry {\n    $translatedText = $deepLy-\u003etranslate('Hello world!', DeepLy::LANG_EN, DeepLy::LANG_AUTO);\n    \n    echo $translatedText; // Prints \"Hallo Welt!\"\n} catch (\\Exception $exception) {\n    echo $exception-\u003egetMessage();\n}\n```\n\nAlways wrap calls of the `translate` method in a try-catch-block, because they might throw an exception if the\narguments are invalid or the API call fails. The exception will have an explanatory message and a specific error code. \n\nInstead of using hardcoded strings as language arguments \nbetter use the language code constants of the `DeepLy` class. The class also offers methods such as\n`getLangCodes($withAuto = true)` and `supportsLangCode($langCode)`. \n\nIf you need to specify advanced settings, use the `setSettings()` method: `$deepLy-\u003esetSettings($glossaryId);`\n\n## Auto-Detect Language\n\n\u003e ⚠️ ATTENTION: Using this method increases the usage statistics of your account!\n\nDeepLy has a method that uses the DeepL API to detect the language of a text:\n\n```php\n$languageCode = $deepLy-\u003edetectLanguage('Hello world!');\n```\n\nThis will return 'EN'. The language of the text has to be one of the supported languages or the result will be incorrect.\nIf you do not need the code of the language but its English name, you may call the `$deepLy-\u003egetLangName($langCode)` method. \n\nThe API, in general, can handle and completely translate texts that contain parts with different languages, \nif the language switch is not within a sentence. The `detectLanguage()` method will however \nonly return the code of _one_ language. It will throw an exception if it is unable to auto-detect the language. \nThis will rarely happen, it is more likely that the API will return a \"false positive\": It will rather detect the wrong\nlanguage than no language at all.\n\n\u003e 💡 An interactive PHP demo script is included. It is located at [demos/demo_detect](demos/demo_detect.php).\n\n## Supported Languages\n\nDeepL(y) supports these languages:\n\n| Code | Language      |     | Code  | Language      |\n|------|---------------|-----|-------|---------------|\n| auto | _Auto detect_ |     | KO    | Korean        |\n| ID   | Indonesian    |     | TR    | Turkish       |\n| IT   | Italian       |     | ZH    | Chinese       |\n| BG   | Bulgarian     |     | LT    | Lithuanian    |\n| CS   | Czech         |     | LV    | Latvian       |\n| DA   | Danish        |     | NB    | Norwegian     |\n| DE   | German        |     | NL    | Dutch         |\n| EL   | Greek         |     | PL    | Polish        |\n| EN   | English       |     | PT    | Portuguese    |\n| ES   | Spanish       |     | RO    | Romanian      |\n| ET   | Estonian      |     | RU    | Russian       |\n| FI   | Finnish       |     | SK    | Slovak        |\n| PT   | French        |     | SL    | Slovenian     |\n| HU   | Hungarian     |     | SV    | Swedish       |\n| JA   | Japanese      |     |       |               |\n\n\u003e 💡 Note that only the source language can be auto-detected.\n\n## Glossaries\n\nTo get a list with information about all your glossaries, do:\n\n```php\n$glossaries = $deepLy-\u003egetGlossaries();\nprint_r($glossaries); // Prints an array with Glossary objects\n```\nOutput:\n```\nArray\n(\n    [0] =\u003e ChrisKonnertz\\DeepLy\\Models\\Glossary Object\n        (\n            [glossaryId] =\u003e 56cab399-ac8e-4a57-aadc-fa95103f2de5\n            [entryCount] =\u003e 2\n            ...\n        )\n    [2] =\u003e ChrisKonnertz\\DeepLy\\Models\\Glossary Object\n        (\n            [glossaryId] =\u003e d9eb53b5-3929-49a1-b5e1-df1eb8be93c9\n            [entryCount] =\u003e 5\n            ...\n        )\n)\n```\n\nTo get information about a specific glossary, do:\n\n```php\n$glossary = $deepLy-\u003egetGlossary('your-glossary-id');\nprint_r($glossary); // Prints a \\stdClass\n```\nOutput:\n```\nChrisKonnertz\\DeepLy\\Models\\Glossary Object\n(\n    [glossaryId] =\u003e d9eb53b5-3929-49a1-b5e1-df1eb8be93c9\n    [name] =\u003e DeepLy Test\n    [ready] =\u003e 1\n    [from] =\u003e en\n    [to] =\u003e de\n    [creationTimeIso] =\u003e 2022-04-21T17:46:31.83913+00:00\n    [creationDateTime] =\u003e DateTime Object\n    [entryCount] =\u003e 2\n)\n```\n\nTo get the translation entries of a specific glossary, do:\n\n```php\n$entries = $deepLy-\u003egetGlossaryEntries('your-glossary-id');\nprint_r($entries);  // Prints an array with string items\n```\nOutput:\n```\nArray\n(\n    [Entry 1 DE] =\u003e Entry 1 EN\n    [Entry 2 DE] =\u003e Entry 2 EN\n)\n```\n\nTo create a new glossary with translation entries, do:\n\n```php\n$glossary = $deepLy-\u003ecreateGlossary('test', 'de', 'en', ['Example DE' =\u003e 'Example EN']);\n```\n\nTo delete an existing glossary, do:\n\n```php\n$deepLy-\u003edeleteGlossary('your-glossary-id');\n```\n\n\u003e 💡 An interactive PHP demo script is included. It is located at [demos/demo_glossaries.php](demos/demo_glossaries.php).\n\n## Documents\n\nTranslating documents consists of three steps. The first step is to upload a document:\n```php\n$filename = __DIR__.'/test_document_original.pdf';\n$result = $deepLy-\u003euploadDocument($filename, 'DE');\n\nvar_dump($result);\n```\nOutput:\n```\nChrisKonnertz\\DeepLy\\Models\\DocumentHandle Object\n(\n  [documentId] =\u003e D014F316B7A173079074BE76F530F846\n  [documentKey] =\u003e 39FF8B10D20621096F23BF96CC103E12074727007C62963CF49AE8A9965D7695\n)\n```\n\u003e 💡 The maximum upload limit for any document is 10 MB and 1.000.000 characters.\n\u003e \n\u003e ⚡ Every file upload is at least billed with 50.000 characters!\n\nThe second step is to wait for the DeepL.com API to finish processing (translating) the document.\nYou can check the state:\n```php\n$result = $deepLy-\u003egetDocumentState($result-\u003edocumentId, $result-\u003edocumentKey);\n\nvar_dump($result);\n```\nOutput:\n```\nChrisKonnertz\\DeepLy\\Models\\DocumentState Object\n(\n    [documentId] =\u003e D014F316B7A173079074BE76F530F846\n    [status] =\u003e done\n    [billedCharacters] =\u003e 50000\n    [secondsRemaining] =\u003e null\n)\n```\nIn this case the document has been processed. \nThis is indicated by \"status\" being \"done\" and \"seconds_remaining\" being *null*.\n\n\u003e 💡 The document life cycle is: *queued* ➜ *translating* ➜ *done* (or *error*)\n\u003e \n\u003e There are constants that you can use to check these values: `DocumentState\\STATUS_DONE` etc.\n\nThe third step is to download the document:\n```php\n$deepLy-\u003edownloadDocument($documentId, $documentKey, 'test_document_translated.pdf');\n```\nIf you do not want to store the file, do:\n```php\n$contents = $deepLy-\u003edownloadDocument($documentId, $documentKey);\n```\n\n\u003e ⚡ A document can only be downloaded once!\n\n\u003e 💡 An interactive PHP demo script is included. It is located at [demos/demo_documents.php](demos/demo_documents.php).\n\n## Usage Statistic\n\nTo get usage statistics, do:\n\n```php\n$usage = $deepLy-\u003eusage(); // Returns an object of type \"Usage\"\n\necho $usage-\u003echaracterCount.'/'.$usage-\u003echaracterLimit\n    . ' characters ('.round($usage-\u003echaracterQuota * 100).'%)';\n```\n\nDepending on the user account type, some usage types will be null.\nLearn more: https://www.deepl.com/de/docs-api/other-functions/monitoring-usage/\n\n## Framework Integration\n\nDeepLy comes with support for Laravel 5.5+ and since it also supports \n[package auto-discovery](https://medium.com/@taylorotwell/package-auto-discovery-in-laravel-5-5-ea9e3ab20518) \nit will be auto-detected. However, you have to store your DeepL API key manually in the `.env` file, like this:\n```\nDEEPL_API_KEY = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n```\n \nAfterwards you can access DeepLy like this: `$ping = \\DeepLy::ping();`\n\n## HTTP Client\n\nPer default DeepLy uses a minimalistic HTTP client based on cURL. If you want to use a different HTTP client,\nsuch as [Guzzle](https://github.com/guzzle/guzzle), create a class that implements the `HttpClient\\HttpClientInterface`\nand makes use of the methods of the alternative HTTP client. Then use `$deepLy-\u003esetHttpClient($yourHttpClient)`\nto inject it.\n\n\u003e 💡 Note: If you experience issues with the integrated cURL client that could be solved by setting the\n\u003e `CURLOPT_SSL_VERIFYPEER` to `false`, first read this:\n\u003e [snippets.webaware.com.au/../](https://snippets.webaware.com.au/howto/stop-turning-off-curlopt_ssl_verifypeer-and-fix-your-php-config/)\n\u003e\n\u003e If it does not help try: `$deepLy-\u003egetHttpClient()-\u003esetSslVerifyPeer(false)`\n\n\u003e 💡 You can set up a proxy with: `$deepLy-\u003egetHttpClient()-\u003esetProxy('ip:port', 'user:password')`\n\n\n## Tests\n\nExport your API key:\n```\nexport DEEPL_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n```\nRun `composer install` from the DeepLy directory, then run the tests:\n```\n./vendor/phpunit/phpunit/phpunit\n```\n\n## Differences to V1\n\nTo upgrade from v1 to v2, make sure you specify the API key when instantiating the DeepLy object.\nApart from the changes mentioned above your v1 code should still work with v2 as long \nas you did not write your own HTTP client or extended the DeepLy class with a custom class.\nTo learn more about the changes, please take a look at the [changelog](CHANGELOG.md).\n\n## Disclaimer\n\nThis is not an official package. It is 100% open source and non-commercial.\n\nDeepL is a product of DeepL GmbH. More info: [deepl.com/publisher.html](https://www.deepl.com/publisher.html)\n\n## Notes\n\n* Texts have to be UTF8-encoded.\n\n* If you are looking for a real-world example application that uses DeepLy, you may take a look at [Translation Factory](https://github.com/chriskonnertz/translation-factory).\n\n* The code of this library is formatted according to the code style defined by the  \n[PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) standard.\n\n* Status of this repository: _Maintained_. Create an [issue](https://github.com/chriskonnertz/DeepLy/issues)\nand you will get a response, usually within 48 hours.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchriskonnertz%2FDeepLy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchriskonnertz%2FDeepLy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchriskonnertz%2FDeepLy/lists"}