[TEST]

CONTRIBUTING.rst

@@ -1,71 +1,40 @@
 .. highlight:: shell
 
 ============
-コントリビュートする方法
+Contributing
 ============
 
-このプロジェクトではコントリビュートを歓迎しています！どんなに小さい貢献でも、あなたのコントリビュートになります。
-
 Contributions are welcome, and they are greatly appreciated! Every little bit
 helps, and credit will always be given.
 
-次のようないくつかの方法で貢献することができます。
-
 You can contribute in many ways:
 
-コントリビュートの種類
-
 Types of Contributions
 ----------------------
 
-バグの報告
-
 Report Bugs
 ~~~~~~~~~~~
 
-https://github.com/nidhaloff/deep_translator/issues
-
-でバクを報告してください。
-
 Report bugs at https://github.com/nidhaloff/deep_translator/issues.
 
-バグを報告する時、以下の３項目を含めて投稿するようにしてください。
-
-* バグの発生したOSの種類とOSバージョンの情報
-* ソフトウェアの設定などのローカル環境の情報
-* バグを再現するための詳細な手順
-
 If you are reporting a bug, please include:
 
 * Your operating system name and version.
 * Any details about your local setup that might be helpful in troubleshooting.
 * Detailed steps to reproduce the bug.
 
-バグの修正
-
 Fix Bugs
 ~~~~~~~~
 
-このリポジトリのイシューを見ることで、バグの情報を確認できます。
-"bug" と "help wanted"でタグ付けされているものは、誰でもバグの修正にコントリビュートできます。
-
 Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
 wanted" is open to whoever wants to implement it.
 
-機能の追加
-
 Implement Features
 ~~~~~~~~~~~~~~~~~~
 
-
-このリポジトリのイシューを見ることで、追加したい機能が確認できます。
-"enhancement" と "help wanted"でタグ付けされているものは、誰でも実装にコントリビュートできます。
-
 Look through the GitHub issues for features. Anything tagged with "enhancement"
 and "help wanted" is open to whoever wants to implement it.
 
-ドキュメントの作成
-
 Write Documentation
 ~~~~~~~~~~~~~~~~~~~
 

ja/CONTRIBUTING.rst

@@ -0,0 +1,125 @@
+.. highlight:: shell
+
+============
+コントリビュートする方法
+============
+
+このプロジェクトではあなたのコントリビュートを歓迎します！どんなに小さい貢献でも、コントリビューターとしてプロジェクトを支援することができます。
+
+次の方法でコントリビュートすることができます。
+
+コントリビュートの種類
+----------------------
+
+バグの報告
+~~~~~~~~~~~
+
+もしバグを発見したらhttps://github.com/nidhaloff/deep_translator/issues でバクを報告してください。
+
+バグを報告する際にはトラブルシューティングしやすいように、以下の項目を含めて投稿するようにしてください。
+
+* バグの発生したOSの種類とOSバージョンの情報
+* ソフトウェアの設定などのローカル環境の情報
+* バグを再現するための詳細な手順
+
+バグの修正
+~~~~~~~~
+
+このリポジトリのイシューを見ることで、バグの情報を確認できます。
+"bug" と "help wanted"でタグ付けされているものは、誰でもバグを修正にしてコントリビュートすることができます。
+
+追加機能の実装
+~~~~~~~~~~~~~~~~~~
+
+このリポジトリのイシューを見ることで、実装待ちの機能が確認できます。
+"enhancement" と "help wanted"でタグ付けされているものは、誰でも実装してコントリビュートすることができます。
+
+ドキュメントの作成
+~~~~~~~~~~~~~~~~~~~
+
+deep_translator は、deep_translator の公式ドキュメントの一部、docstrings、あるいはウェブ上のブログ記事や記事など、常により多くのドキュメントを求めています。
+
+
+意見・提案
+~~~~~~~~~~~~~~~
+
+意見・提案をする最も適切な方法は https://github.com/nidhaloff/deep_translator/issues に投稿することです。
+
+もし、新しい機能を提案したければ以下の項目を留意してください。:
+
+* 新しい機能の動作をできるだけ詳しく説明してください。 
+* 実装しやすいように機能の規模は限定するようにしてください。
+* このプロジェクトがボランティアから成り立っていることと、コントリビュートを歓迎する精神を忘れないでください。
+  
+
+開発環境の構築
+------------
+
+コントリビュートの準備はできましたか？ここからは`deep_translator`の開発環境を構築する方法について説明します。
+
+1. GitHub で`deep_translator` をフォークする.
+2. フォークしたものをローカルリポジトリとしてクローンする。::
+
+    $ git clone git@github.com:your_name_here/deep_translator.git
+
+3. virtualenvの作成とインストールを行う。virtualenvwrapperがインストール済みとすると、以下のコマンドでローカルに開発環境を構築できる。::
+
+    $ mkvirtualenv deep_translator
+    $ cd deep_translator /
+    $ python setup.py develop
+
+4. ローカルで開発を行うために新しいブランチを作成する。::
+
+    $ git checkout -b name-of-your-bugfix-or-feature
+
+   これでローカルリポジトリに変更を加えることができるようになります。
+
+5. 変更が終わったらflake8のコードチェックとテストを通過するようにする。この時、toxで複数バージョンのPythonで動作することを確認する。::
+
+    $ flake8 deep_translator tests
+    $ python setup.py test or pytest
+    $ tox
+
+　　flake8とtoxのインストールは、virtualenvでpip installを行うことで可能です。
+
+6. 変更をコミットし、自分のリモートリポジトリにプッシュする。::
+
+    $ git add .
+    $ git commit -m "Your detailed description of your changes."
+    $ git push origin name-of-your-bugfix-or-feature
+
+7. GitHub からプルリクエストを送る.
+
+プルリクエストにあたって
+-----------------------
+
+プルリクエストを送る前に以下のガイドラインに従っているか確認してください。:
+
+1. プルリクエストにテストが含まれている。
+
+2. プルリクエストで機能が追加された場合、ドキュメントを更新する必要があります。新しい機能について関数内にdocstringで記述し、それに加えてリストREADME.rstのリストに追加してください。
+
+3.　プルリクエストはPython 3.5,3.6,3.7,3.8またはPyPyで動作することが望まれます。
+https://travisci.com/nidhaloff/deep_translator/pull_requests　を確認し、サポートされている全てのPythonバージョンでテストを通過することを確認してください。
+
+
+ヒント
+----
+
+テストのサブセットを実行するには以下のコマンドが利用できます。::
+
+$ pytest tests.test_deep_translator
+
+
+デプロイの方法
+---------
+
+メンテナンス担当者のためにデ���ロイの方法を記しておきます。
+まず、全ての変更がコミットされていることを確認してください。(HISTORY.rstのエントリを含む).
+次に、以下のコマンドを実行します::
+
+$ bump2version patch # possible: major / minor / patch
+$ git push
+$ git push --tags
+
+Travisはテストを通過することを確認したら、PyPIにデプロイします。

ja/README.rst

@@ -0,0 +1,359 @@
+****************
+deep_translator
+****************
+
+
+.. image:: https://img.shields.io/pypi/v/deep_translator.svg
+        :target: https://pypi.python.org/pypi/deep_translator
+.. image:: https://img.shields.io/travis/nidhaloff/deep_translator.svg
+        :target: https://travis-ci.com/nidhaloff/deep_translator
+.. image:: https://readthedocs.org/projects/deep-translator/badge/?version=latest
+        :target: https://deep-translator.readthedocs.io/en/latest/?badge=latest
+        :alt: Documentation Status
+.. image:: https://img.shields.io/pypi/l/deep-translator
+        :target: https://pypi.python.org/pypi/deep_translator
+
+.. image:: https://img.shields.io/pypi/dm/deep-translator
+        :target: https://pypi.python.org/pypi/deep_translator
+.. image:: https://img.shields.io/pypi/status/deep-translator
+        :target: https://pypi.python.org/pypi/deep_translator
+.. image:: https://img.shields.io/pypi/wheel/deep-translator
+        :target: https://pypi.python.org/pypi/deep_translator
+
+.. image:: https://img.shields.io/github/last-commit/nidhaloff/gpx_converter
+        :alt: GitHub last commit
+        :target: https://pypi.python.org/pypi/deep_translator
+
+.. image:: https://img.shields.io/twitter/url?url=https%3A%2F%2Ftwitter.com%2FNidhalBaccouri
+        :alt: Twitter URL
+        :target: https://twitter.com/NidhalBaccouri
+
+.. image:: https://img.shields.io/badge/$-buy%20me%20a%20coffee-ff69b4.svg?style=social
+   :target: https://www.buymeacoffee.com/nidhaloff?new=1
+
+
+=======================
+Translation for humans
+=======================
+
+A flexible **FREE** and **UNLIMITED** tool to translate between different languages in a simple way using multiple translators.
+
+
+* Free software: MIT license
+* Documentation: https://deep-translator.readthedocs.io.
+
+==========
+Motivation
+==========
+
+I needed to translate a text using python. It was hard to find a simple way to do it.
+There are other libraries that can be used for this task, but most of them
+are **buggy, not free, limited, not supported anymore or complex to use.**
+
+Therefore, I decided to build this simple tool. It is 100% free, unlimited, easy to use and provide
+support for all languages.
+
+Basically, my goal was to integrate support for multiple famous translators
+in this tool.
+
+======================
+When you should use it
+======================
+
+- If you want to translate text using python
+- If you want to translate from a file
+- If you want to get translations from many sources and not only one
+- If you want to automate translations
+- If you want to compare different translations
+- If you want to detect language automatically
+
+======================
+Why you should use it
+======================
+
+- High level of abstraction
+- Automatic language detection
+- Easy to use and extend
+- It's the only python tool that integrates many translators
+- Stable
+- Support for most famous universal translators
+
+========
+Features
+========
+
+* Support for google translate
+* Support for Pons translator (pons.com)
+* Support for the Linguee translator
+* Support for the Mymemory translator
+* Automatic language detection
+* Translate directly from a text file
+* Get multiple translation for a word
+* Automate the translation of different paragraphs in different languages
+* Translate directly from terminal (version >= 1.1.0)
+
+=============
+Installation
+=============
+
+Install the stable release:
+
+.. code-block:: console
+
+    $ pip install -U deep_translator
+
+take a look at the docs if you want to install from source.
+
+=====
+Usage
+=====
+
+In this section, demos on how to use all different integrated translators in this tool are provided.
+This includes the google, pons, linguee and mymemory translator (at least for now). Perhaps more
+translators will be integrated in the future.
+
+Imports
+========
+
+.. code-block:: python
+
+    from deep_translator import (GoogleTranslator,
+                                 PonsTranslator,
+                                 LingueeTranslator,
+                                 MyMemoryTranslator,
+                                 detect_language)
+
+
+Check Supported Languages
+==========================
+
+.. note::
+
+    You can check the supported languages of each translator by calling the
+    get_supported_languages function as a static method.
+
+.. code-block:: python
+
+    # default return type is a list
+    langs_list = GoogleTranslator.get_supported_languages()  # output: [arabic, french, english etc...]
+
+    # alternatively, you can the dictionary containing languages mapped to their abbreviation
+    langs_dict = GoogleTranslator.get_supported_languages(as_dict=True)  # output: {arabic: ar, french: fr, english:en etc...}
+
+Language Detection
+===================
+
+.. note::
+
+    You can also detect language automatically. Notice that this package is free and my goal is to keep it free.
+    Therefore, you will need to get your own api_key if you want to use the language detection function.
+    I figured out you can get one for free here: https://detectlanguage.com/documentation
+
+.. code-block:: python
+
+    lang = detect_language('bonjour la vie', api_key='your_api_key')
+    print(lang) # output: fr
+
+
+Google Translate
+=================
+
+.. code-block:: python
+
+    text = 'happy coding'
+
+- You can use automatic language detection to detect the source language:
+
+.. code-block:: python
+
+    translated = GoogleTranslator(source='auto', target='german').translate(text=text)
+
+- You can pass languages by name:
+
+.. code-block:: python
+
+    translated = GoogleTranslator(source='english', target='german').translate(text=text)
+
+- Alternatively, you can pass languages by their abbreviation:
+
+.. code-block:: python
+
+    translated = GoogleTranslator(source='en', target='de').translate(text=text)
+
+- Translate from a file:
+
+.. code-block:: python
+
+    translated = GoogleTranslator(source='auto', target='german').translate_file('path/to/file')
+
+- Automate translation by detecting the source language and translate it automatically to the desired language
+
+.. code-block:: python
+
+    # or maybe you have many sentences in different languages and want to automate the translation process
+    translated = GoogleTranslator(source='auto', target='de').translate_sentences([your_list_of_sentences])
+
+
+
+PONS Translator
+===============
+
+.. note::
+
+    You can pass the languages by the name or by abbreviation just like
+    previous examples using GoogleTranslate
+
+.. code-block:: python
+
+    word = 'awesome'
+
+- Simple Translation
+
+.. code-block:: python
+
+    translated_word = PonsTranslator(source='english', target='french').translate(word)
+
+    # pass language by their abbreviation
+    translated_word = PonsTranslator(source='en', target='fr').translate(word)
+
+- Return all synonyms or words that matches
+
+.. code-block:: python
+
+    # set the argument return_all to True if you want to get all synonyms of the word to translate
+    translated_word = PonsTranslator(source='english', target='french').translate(word, return_all=True)
+
+
+
+Linguee Translator
+===================
+
+
+.. code-block:: python
+
+    word = 'good'
+
+- Simple Translation
+
+.. code-block:: python
+
+    translated_word = LingueeTranslator(source='english', target='french').translate(word)
+
+    # pass language by their abbreviation
+    translated_word = LingueeTranslator(source='en', target='fr').translate(word)
+
+- Return all synonyms or words that matches
+
+.. code-block:: python
+
+    # set the argument return_all to True if you want to get all synonyms of the word to translate
+    translated_word = LingueeTranslator(source='english', target='french').translate(word, return_all=True)
+
+
+Mymemory Translator
+====================
+
+.. note::
+
+    You can use the automatic language detection with mymemory by passing
+    "auto" as a value for the source language
+
+.. code-block:: python
+
+    text = 'Keep it up. You are awesome'
+
+    translated = MyMemoryTranslator(source='auto', target='french').translate(text)
+
+Usage from Terminal
+====================
+
+For a quick access, you can use the deep_translator from terminal. For this to work, you need to provide
+the right arguments, which are the translator you want to use, source language, target language and the text
+you want to translate.
+
+For example, provide "google" as an argument to use the google translator. Alternatively you can use
+the other supported translators. Just read the documentation to have an overview about the supported
+translators in this library.
+
+.. code-block:: console
+
+    $ deep_translator --translator "google" --source "english" --target "german" --text "happy coding"
+
+Or you can go for the short version:
+
+.. code-block:: console
+
+    $ deep_translator -trans "google" -src "english" -tg "german" -txt "happy coding"
+
+If you want, you can also pass the source and target language by their abbreviation
+
+.. code-block:: console
+
+    $ deep_translator -trans "google" -src "en" -tg "de" -txt "happy coding"
+
+Side Hint
+==========
+
+Generally, I find the google and mymemory translators suitable for translating sentences, whereas
+the pons and linguee translators are good choices if you want to translate words.
+
+========
+Links
+========
+Check this article on medium to know why you should use the deep-translator package and how to translate text using python.
+https://medium.com/@nidhalbacc/how-to-translate-text-with-python-9d203139dcf5
+
+===========================
+The Translator++ mobile app
+===========================
+
+.. image:: assets/app-icon.png
+    :width: 100
+    :alt: Icon of the app
+
+
+After developing the deep_translator, I realised how cool this would be if I can use it as an app on my mobile phone.
+Sure, there is google translate, pons and linguee apps etc.. but isn't it cooler to make an app where all these
+translators are integrated?
+
+Long story short, I started working on the app. I decided to use the `kivy framework <https://kivy.org/#home/>`_ since
+I wanted to code in python and to develop a cross platform app.
+I open sourced the `Translator++ app <https://github.com/nidhaloff/deep-translator-app/>`_ on my github too.
+Feel free to take a look at the code or make a pull request ;)
+
+.. note::
+    The Translator++ app is based on the deep_translator package. I just built the app to prove the capabilities
+    of the deep_translator package ;)
+
+I published the first release on google play store on 02-08-2020
+
+Here are some screenshots:
+
+- Phone
+
+.. image:: assets/translator1.jpg
+    :width: 30%
+    :height: 200
+    :alt: screenshot1
+.. image:: assets/translator2.jpg
+    :width: 30%
+    :height: 200
+    :alt: screenshot2
+.. image:: assets/spinner.jpg
+    :width: 30%
+    :height: 200
+    :alt: spinner
+
+- Tablet:
+
+.. image:: assets/hz_view.png
+    :width: 100%
+    :height: 300
+    :alt: screenshot3
+
+==========
+Next Steps
+==========
+
+Take a look in the examples folder for more :)
+Contributions are always welcome. Feel free to make a pull request and give me a feedback if you found the package useful or you are using it :)