Permalink
Browse files

Added a README and a LICENSE

  • Loading branch information...
1 parent f5632f1 commit 0d99aa5f682a9513ad28a7c3a2f1fa09ec313292 @matthiasnoback committed Nov 1, 2012
Showing with 111 additions and 0 deletions.
  1. +19 −0 LICENSE
  2. +92 −0 README.md
View
19 LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2012 Matthias Noback
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
View
92 README.md
@@ -0,0 +1,92 @@
+# PHP library for the Microsoft Translator V2 API
+
+By Matthias Noback
+
+## Installation
+
+Using Composer, add to ``composer.json``:
+
+ {
+ "require": {
+ "matthiasnoback/microsoft-translator": "*"
+ }
+ }
+
+Then using the Composer binary:
+
+ php composer.phar install
+
+## Usage
+
+This library uses the Buzz browser to make calls to the [Microsoft Translator V2 API](http://msdn.microsoft.com/en-us/library/ff512419.aspx).
+
+You need to register your application at the [Azure DataMarket](https://datamarket.azure.com/developer/applications) and
+thereby retrieve a "client id" and a "client secret". These kan be used to instantiate the ``AccessTokenProvider`` on which
+the ``MicrosoftTranslator`` depends:
+
+ <?php
+
+ use Buzz\Browser;
+ use MatthiasNoback\MicrosoftOAuth\AccessTokenProvider;
+ use MatthiasNoback\MicrosoftTranslator\MicrosoftTranslator;
+
+ $browser = new Browser();
+
+ $clientId = '[YOUR-CLIENT-ID]';
+ $clientSecret = '[YOUR-CLIENT-SECRET]';
+
+ $accessTokenProvider = new AccessTokenProvider($browser, $clientId, $clientSecret);
+
+ $translator = new MicrosoftTranslator($browser, $accessTokenProvider);
+
+### Optional: enable the access token cache
+
+Each call to the translator service is preceded by a call to Microsoft's OAuth server. Each access token however, may be
+cached for 10 minutes, so you should also use the built-in ``AccessTokenCache``:
+
+ <?php
+
+ use MatthiasNoback\MicrosoftOAuth\AccessTokenCache;
+ use Doctrine\Common\Cache\ArrayCache;
+
+ $cache = new ArrayCache();
+ $accessTokenCache = new AccessTokenCache($cache);
+ $accessTokenProvider->setCache($accessTokenCache);
+
+The actual cache provider can be anything, as long as it implements the ``Cache`` interface from the Doctrine Common library.
+
+## Making calls
+
+### Translate a string
+
+ $translatedString = $translator->translate('This is a test', 'nl', 'en');
+
+ // $translatedString will be 'Dit is een test', which is Dutch for...
+
+### Detect the language of a string
+
+ $text = 'This is a test';
+
+ $detectedLanguage = $translator->detect($text);
+
+ // $detectedLanguage will be 'en'
+
+### Get a spoken version of a string
+
+ $text = 'My name is Matthias';
+
+ $spoken = $translator->speak($text, 'en', 'audio/mp3', 'MaxQuality');
+
+ // $spoken will be the raw MP3 data, which you can save for instance as a file
+
+## Tests
+
+Take a look at the tests to find out what else you can do with the API.
+
+To fully enable the test suite, you need to copy ``phpunit.xml.dist`` to ``phpunit.xml`` and replace the placeholder
+values with their real values (i.e. client id, client secret and a location for storing spoken text files).
+
+## TODO
+
+There are some more calls to be implemented, and also some more tests to be added. I am also working on a bundle for Symfony2,
+which will make the translator available as a service and will take care of setting up the cache and the browser.

0 comments on commit 0d99aa5

Please sign in to comment.