deep-translator
A flexible free and unlimited python tool to translate between different languages in a simple way using multiple translators
Rank: #3141Downloads: 1,559,304 (30 days)Stars: 1,964Forks: 242
Description
##################
deep-translator
##################
.. image:: ../assets/icon.jpg
:width: 100
:align: center
:alt: deep-translator-icon
|
.. 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://github.com/nidhaloff/deep-translator/actions/workflows/build.yml
.. 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/status/deep-translator
:target: https://pypi.python.org/pypi/deep-translator
.. image:: https://pepy.tech/badge/deep-translator
:target: https://pepy.tech/project/deep-translator
.. image:: https://img.shields.io/pypi/wheel/deep-translator
:target: https://pypi.python.org/pypi/deep-translator
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit
:target: https://github.com/pre-commit/pre-commit
.. image:: https://img.shields.io/twitter/url?url=https%3A%2F%2Ftwitter.com%2FNidhalBaccouri
:alt: Twitter URL
:target: https://twitter.com/NidhalBaccouri
=======================
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.
* Swagger API: https://deep-translator-api.azurewebsites.net/docs.
|
|
.. contents:: Table of Contents
:depth: 3
|
|
==========
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 provides
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 use ChatGpt for translations
- If you want to compare different translations
- If you want to detect language automatically
======================
Why you should use it
======================
- It's the only python tool that integrates many translators
- Multi language support
- Support for ChatGpt (version >= 1.11.0)
- Supports batch translation
- High level of abstraction
- Automatic language detection
- Easy to use and extend
- Support for most famous universal translators
- Stable and maintained regularly
- The API is very easy to use
- Proxy integration is supported
========
Features
========
* Support for `google translate <https://translate.google.com/>`_
* Support for the `microsoft translator <https://www.microsoft.com/en-us/translator//>`_ (version >= 1.3.5)
* Support for `Pons translator <https://de.pons.com/>`_
* Support for the `Linguee translator <https://www.linguee.com/>`_
* Support for the `Mymemory translator <https://mymemory.translated.net/>`_
* Support for the `Yandex translator <https://yandex.com/>`_ (version >= 1.2.1)
* Support for the `QcriTranslator translator <https://mt.qcri.org/api/>`_ (version >= 1.2.4)
* Support for the `DeeplTranslator translator <https://www.deepl.com/en/translator/>`_ (version >= 1.2.5)
* Support for the `Papago translator <https://papago.naver.com/>`_ (version >= 1.4.4)
* Support for the `Libre translator <https://libretranslate.com/>`_
* Support for ChatGpt
* Support for proxy usage
* Automatic single language detection
* Batch language detection
* Translate directly from a text file
* Translate docx files (version >= 1.9.4)
* Translate PDF files (version >= 1.9.4)
* 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
$ poetry add deep-translator # for poetry usage
take a look at the docs if you want to install from source.
Also, you can install extras if you want support for specific use case. For example, translating Docx and PDF files
.. code-block:: console
$ pip install deep-translator[docx] # add support for docx translation
$ pip install deep-translator[pdf] # add support for pdf translation
$ pip install deep-translator[ai] # add support for ChatGpt
$ poetry add deep-translator --extras "docx pdf ai" # for poetry usage
============
Quick Start
============
.. code-block:: python
from deep_translator import GoogleTranslator
# Use any translator you like, in this example GoogleTranslator
translated = GoogleTranslator(source='auto', target='de').translate("keep it up, you are awesome") # output -> Weiter so, du bist großartig
or using proxies:
.. code-block:: python
from deep_translator import GoogleTranslator
proxies_example = {
"https": "34.195.196.27:8080",
"http": "34.195.196.27:8080"
}
translated = GoogleTranslator(source='auto', target='de', proxies=proxies_example).translate("keep it up, you are awesome") # output -> Weiter so, du bist großartig
or even directly from terminal:
.. code-block:: console
$ deep-translator --source "en" --target "de" --text "hello world"
or shorter
$ dt -tg de -txt "hello world"
=====
Usage
=====
In this section, demos on how to use all different integrated translators in this tool are provided.
.. note::
You can always pass the languages by the name or by abbreviation.
*Example*: If you want to use english as a source or target language, you can pass **english** or **en** as an argument
.. note::
For all translators that require an ApiKey, you can either specify it as an argument to the translator class
or you can export it as an environment variable, this way you won't have to provide it to the class.
*Example*: export OPENAI_API_KEY="your_key"
Imports
--------
.. code-block:: python
from deep_translator import (GoogleTranslator,
ChatGptTranslator,
MicrosoftTranslator,
PonsTranslator,
LingueeTranslator,
MyMemoryTranslator,
YandexTranslator,
PapagoTranslator,
DeeplTranslator,
QcriTranslator,
single_detection,
batch_detection)
Check Supported Languages
---------------------------
.. note::
You can check the supported languages of each translator by calling the
get_supported_languages function.
.. 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
- Single Text Detection
.. code-block:: python
lang = single_detection('bonjour la vie', api_key='your_api_key')
print(lang) # output: fr
- Batch Detection
.. code-block:: python
lang = batch_detection(['bonjour la vie', 'hello world'], api_key='your_api_key')
print(lang) # output: [fr, en]
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='de').translate(text=text)
- You can pass languages by name or by abbreviation:
.. code-block:: python
translated = GoogleTranslator(source='auto', target='german').translate(text=text)
# Alternatively, you can pass languages by their abbreviation:
translated = GoogleTranslator(source='en', target='de').translate(text=text)
- You can also reuse the Translator class and change/update its properties.
(Notice that this is important for performance too, since instantiating new objects is expensive)
.. code-block:: python
# let's say first you need to translate from auto to german
my_translator = GoogleTranslator(source='auto', target='german')
result = my_translator.translate(text=text)
print(f"Translation using source = {my_translator.source} and target = {my_translator.target} -> {result}")
# let's say later you want to reuse the class but your target is french now
# This is the best practice and how you should use deep-translator.
# Please don't over-instantiate translator objects without a good reason, otherwise you will run into performance issues
my_translator.target = 'fr' # this will override the target 'german' passed previously
result = my_translator.translate