Merge pull request #17 from Baby-Markt/v2-all-post

* code check * run unit/integration tests * manual tests with different combinations of parameters
Baby-Markt · Sep 8, 2020 · 022fd35 · 022fd35
2 parents 7190c95 + 169f0f5
commit 022fd35
Show file tree

Hide file tree

Showing 5 changed files with 773 additions and 461 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,146 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+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]
+
+## [2.0.0] - 2020-09-??
+####Major overhaul of the Library with some Breaking changes. Please read before updating!
+### Added
+- Ability to change the API-Host
+- Support for the full Range of Request Parameters offered by DeepL
+- Ability to check Languages supported by DeepL-Api (source and target)
+- Ability to monitor API usage
+### Changed
+- **Breaking Change!** tagHandling-Parameter for translate-function was changed from array to string. 
+- **Breaking Change!** translate now always returns an array, because in our internal usages we found, that we always converted the string to an array anyway.
+- Errocodes & Messages come now directly from DeepL
+- all Requests are now send as POST as it is recommended by DeepL
+- all Parameters except the API-key are send in the Requestbody
+- Tests are now split into Unit- and Intergration-Tests (which need an API-Key to run)
+### Removed
+- internal Error-codes
+- internal storage of source- and target-languages
+
+## [1.1.0] - 2020-08-07
+### Changed
+- use API v2 as default [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+## [1.0.11] - 2020-06-23
+### Added
+- Add supported languages to Readme [@bestog](https://github.com/bestog)
+- Add Japanese and Chinese to supported languages [@bestog](https://github.com/bestog)
+- add formality parameter [@tomschwiha](https://github.com/tomschwiha)
+- Added possible Portuguese variants [@interferenc](https://github.com/interferenc)
+### Changed
+- Update README.md (added Flaggs)  [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+- Add portuguese varieties in README [@Sasti](https://github.com/Sasti)
+
+## [1.0.10] - 2020-02-26
+### Added
+- create clover.xml in travis and push to scrutinizer
+### Changed
+- update scrutinizer config
+- change keyword in composer.json
+
+all by [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+## [1.0.9] - 2020-02-03
+### Added
+- add phpcs to project and integrate it into travis-ci configuration
+### Changed
+- update composer description
+- fix scrutinizer ci url
+- disable xdebug in composer for travis-ci 
+- update testing sequence 
+
+all by [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+## [1.0.8] - 2019-11-28
+### Changed
+- update tests for travis deepl api testing 
+- fix testTranslateIgnoreTagsSuccess 
+- update php version 
+
+all by [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+
+## [1.0.7] - 2019-11-25
+### Added
+- packagist status to README.md file [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+### Changed
+- Fix ignore tags  [@tomschwiha](https://github.com/tomschwiha)
+- Update README.md [@tomschwiha](https://github.com/tomschwiha)
+
+
+## [1.0.6] - 2019-09-05
+### Added
+- add php 5.5 to travis ci test [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+### Changed
+- Fix wrong error message [@shamimmoeen](https://github.com/shamimmoeen)
+- set dist precise for php 5.4 and php 5.5 in travis configuration [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+
+## [1.0.5] - 2019-02-20
+### Added
+- deepl v2 api support and [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+### Changed
+-  fix some little errors [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+
+## [1.0.4] - 2019-02-14
+### Added
+- Add PT and RU to supported languages [@floranpagliai](https://github.com/floranpagliai)
+### Changed
+- replace travis build php nightly build with php 7.3 [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+### Removed
+
+## [1.0.3] - 2018-19-23
+### Added
+- Add tag_handling optional param [@floranpagliai](https://github.com/floranpagliai)
+- Add tagHandling test [@floranpagliai](https://github.com/floranpagliai)
+- Add ignore_tag optional param [@floranpagliai](https://github.com/floranpagliai)
+- Add test for ignore tags [@floranpagliai](https://github.com/floranpagliai)
+- Add var typing on setIgnoreTags method [@floranpagliai](https://github.com/floranpagliai)
+### Changed
+- Fixed array syntax [@floranpagliai](https://github.com/floranpagliai)
+- Fixed array syntax [@floranpagliai](https://github.com/floranpagliai)
+- Fixed buildUrl test [@floranpagliai](https://github.com/floranpagliai)
+
+
+## [1.0.2] - 2018-06-04
+### Changed
+- send text as POST body to solve 414 uri too long error [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+## [1.0.1] - 2018-06-12
+### Changed
+- fix travis-ci build status image [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+- update translate method return [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+- update readme [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+
+## [1.0.0] - 2018-06-12
+Initial public Release [@arkadiusjonczek](https://github.com/arkadiusjonczek)
+
+
+
+
+[Unreleased]: https://github.com/Baby-Markt/deepl-php-lib/compare/master...head
+[2.0.0]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/2.0.0
+[1.1.0]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.1.0
+[1.0.11]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.11
+[1.0.10]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.10
+[1.0.9]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.9
+[1.0.8]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.8
+[1.0.7]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.7
+[1.0.6]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.6
+[1.0.5]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.5
+[1.0.4]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.4
+[1.0.3]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.3
+[1.0.2]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.2
+[1.0.1]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.1
+[1.0.0]: https://github.com/Baby-Markt/deepl-php-lib/releases/tag/v1.0.0
+
+What is a changelog?
diff --git a/README.md b/README.md
@@ -9,7 +9,11 @@
 
 Simple PHP Library for DeepL API. You can translate one or multiple text strings (up to 50) per request.
 
-🇬🇧🇩🇪🇫🇷🇪🇸🇵🇹🇮🇹🇷🇺🇯🇵🇨🇳🇵🇱🇳🇱🇸🇪🇩🇰🇫🇮🇬🇷🇨🇿🇷🇴🇭🇺🇸🇰🇧🇬🇸🇮🇱🇹🇱🇻🇪🇪🇲🇹
+🇩🇪🇬🇧🇺🇸🇪🇸🇲🇽🇫🇷🇮🇹🇯🇵🇳🇱🇵🇱🇵🇹🇧🇷🇷🇺🇨🇳
+
+[Official DeepL API][link-deepl]
+
+[CHANGELOG](CHANGELOG.md)
 
 ## Install
 
@@ -28,11 +32,12 @@ $authKey = '<AUTH KEY>';
 $deepl   = new DeepL($authKey);
 ```
 
+### Translate
 Translate one Text:
 
 ```php
 $translatedText = $deepl->translate('Hallo Welt', 'de', 'en');
-echo $translatedText;
+echo $translatedText[0]['text'].PHP_EOL;
 ```
 
 Translate multiple Texts:
@@ -47,24 +52,60 @@ $text = array(
 $translations = $deepl->translate($text, 'de', 'en');
 
 foreach ($translations as $translation) {
-    echo $translation['text'];
+    echo $translation['text'].PHP_EOL;
 }
 ```
+
+| param               | Description                                                                                                                                                                                                                                                                                                                                                                                                               |
+|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| $text               | Text to be translated. Only UTF8-encoded plain text is supported. The parameter may be specified as an Array and translations are returned in the same order as they are requested. Each of the array values may contain multiple sentences. Up to 50 texts can be sent for translation in one request.                                                                                                            |
+| $sourceLang         | Language of the text to be translated. <br>default: de                                                                                                                                                                                                                                                                                                                                                                                   |
+| $targetLang         | The language into which the text should be translated. <br> default: en                                                                                                                                                                                                                                                                                                                                                                    |
+| $tagHandling        | Sets which kind of tags should be handled. Options currently available: "xml"                                                                                                                                                                                                                                                                                                                                             |
+| $ignoreTags         | Array of XML tags that indicate text not to be translated. <br> default: null                                                                                                                                                                                                                                                                                                                                                  |
+| $formality          | Sets whether the translated text should lean towards formal or informal language. This feature currently works for all target languages except "EN" (English), "EN-GB" (British English), "EN-US" (American English), "ES" (Spanish), "JA" (Japanese) and "ZH" (Chinese).<br><br>Possible options are:<br>"default" (default)<br>"more" - for a more formal language<br>"less" - for a more informal language |
+| $splitSentences     | Array of XML tags which always cause splits  <br> default: null                                                                                                                                                                                                                                                                                                                                                                |
+| $preserveFormatting | Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects. Possible values are:<br>"0" (default)<br>"1"<br>The formatting aspects affected by this setting include:<br>Punctuation at the beginning and end of the sentence<br>Upper/lower case at the beginning of the sentence                                                                          |
+| $nonSplittingTags   | Comma-separated list of XML tags which never split sentences.   <br> default: null                                                                                                                                                                                                                                                                                                                                                            |
+| $outlineDetection   | See: https://www.deepl.com/docs-api/handling-xml/outline-detection/ <br> default: 1                                                                                                                                                                                                                                                                                                                                                     |
+| $splittingTags      | Array of XML tags which always cause splits. <br> default: null                                                                                                                                                                                                                                                                                                                                                              |
+
 ### Supported languages
-* `de` - German
-* `en` - English
-* `fr` - French
-* `it` - Italian
-* `ja` - Japanese
-* `es` - Spanish
-* `nl` - Dutch
-* `pl` - Polish
-* `pt` - Portuguese
-* `pt-pt` - Portuguese variant
-* `pt-br` - Portuguese variant
-* `ru` - Russian
-* `zh` - Chinese
+In Version 2 we removed the internal List of supported Languages.
+Instead, you can now get an array with the supported Languages directly form DeepL:
+
+```php
+$languagesArray = $deepl->languages();
+
+foreach ($languagesArray as $language) {
+    echo 'Name: '.$language['name'].' Api-Shorthand: '.$language['language'].PHP_EOL;
+}
+```
+You can check for the supported Source-Languages:
+```php
+$sourceLanguagesArray = $deepl->languages('source');
 
+foreach ($sourceLanguagesArray as $srouceLanguage) {
+    echo 'Name: '.$srouceLanguage['name'].' Api-shorthand: '.$srouceLanguage['language'].PHP_EOL;
+}
+```
+
+Check for the supported Target-Languages:
+```php
+$targetLanguagesArray = $deepl->languages('target');
+
+foreach ($targetLanguagesArray as $targetLanguage) {
+    echo 'Name: '.$targetLanguage['name'].' Api-Shorthand: '.$targetLanguage['language'].PHP_EOL;
+}
+```
+### Monitoring usage
+You can now check ow much you translate, as well as the limit:
+```php
+$usageArray = $deepl->usage();
+
+echo 'You have used '.$usageArray['character_count'].' of '.$usageArray['character_limit'].' in the current billing period.'.PHP_EOL;
+
+```
 ## Testing
 
 Run PHP_CodeSniffer Tests:
@@ -93,7 +134,7 @@ composer test:all
 
 ## Credits
 
-- [Arkadius Jonczek][link-author]
+- [babymarkt.de GmbH][link-author]
 - [All Contributors][link-contributors]
 
 ## License
@@ -112,5 +153,6 @@ The MIT License (MIT). Please see [License File](LICENSE.md) for more informatio
 [link-scrutinizer]: https://scrutinizer-ci.com/g/Baby-Markt/deepl-php-lib/code-structure
 [link-code-quality]: https://scrutinizer-ci.com/g/Baby-Markt/deepl-php-lib
 [link-downloads]: https://packagist.org/packages/babymarkt/deepl-php-lib
-[link-author]: https://github.com/arkadiusjonczek
+[link-author]: https://github.com/Baby-Markt
 [link-contributors]: ../../contributors
+[link-deepl]: https://www.deepl.com/docs-api/introduction/