## tranzlate
A wrapper around the [`translators`](https://pypi.org/project/translators/) package, providing a simpler interface for the translation of text, files, markup and BeautifulSoup.
## Installation
Perform a quick install with pip:
```bash
pip install tranzlate
```
## Usage
> Ensure you have `beautifulsoup4` installed if you want to translate markup or BeautifulSoup. Run `pip install beautifulsoup4` in your terminal.
### Create a translator
The `Translator` class is the main interface for the package. It can be used to translate text, bytes, files, markup and BeautifulSoup. To create an instance of the `Translator` class, simply import the `tranzlate` package and instantiate a `Translator`:
```python
import tranzlate
translator = tranzlate.Translator()
```
### Use a custom translation engine
By default, the `Translator` class uses Bing Translator as its translation engine. Based on test results, Bing is the most reliable translation engine. However, you can use any translation engine that is supported by the translators package by passing the name of the engine to the `Translator` class on instantiation:
In this example, we will use Google Translate as our translation engine:
```python
import tranzlate
google = tranzlate.Translator('google')
```
To get a list of all supported translation engines:
```python
import tranzlate
print(tranzlate.Translator.engines())
# Output:
# ['bing', 'google', 'yandex', 'baidu', 'sogou', 'tencent', 'deepl', 'alibaba', ...]
```
### Detect language
```python
import tranzlate
text = 'Good Morning!'
language = tranzlate.Translator.detect_language(text)
print(language)
# Output: en
```
### Translate text, bytes, markup and BeautifulSoup
Translate text, markup or a soup using the `translate` method of the `Translator` class. The `translate` method is a general purpose method that can be used to translate text, bytes and markup.
#### Translate text/bytes
```python
import tranzlate
bing = tranzlate.Translator("bing")
text = 'Good Morning!'
translation = bing.translate(text, target_lang='yo')
print(translation)
# Output: Eku ojumo!
```
#### Translate markup
```python
import tranzlate
bing = tranzlate.Translator("bing")
markup = '<p>Good Morning!</p>'
translated_markup = bing.translate(markup, target_lang='yo', is_markup=True)
print(translated_markup)
# Output: <p>Eku ojumo!</p>
```
#### Translate BeautifulSoup
```python
import tranzlate
from bs4 import BeautifulSoup
baidu = tranzlate.Translator("baidu")
markup = '<p>Good Morning!</p>'
soup = BeautifulSoup(markup, 'html.parser')
translated_soup = baidu.translate_soup(soup, target_lang='fr')
```
However, there are specialized methods for translating text, markup and BeautifulSoup objects. These methods are `translate_text`, `translate_markup` and `translate_soup` respectively.
### Translate files
To translate files, we use the `translate_file` method.
```python
import tranzlate
bing = tranzlate.Translator() # Bing is used by default
translated_file = bing.translate_file('path/to/file.txt', src_lang="en", target_lang='yo')
```
It is advisable to specify the source language when performing translations as it helps the translation engine to provide more accurate translations.
### Use a proxy
To use a proxy, simply pass your proxies on translation:
```python
import tranzlate
deepl = tranzlate.Translator("deepl")
text = 'Good Morning!'
translation = deepl.translate(text, target_lang='yo', proxies={'https': 'https://<proxy>:<port>'})
print(translation)
```
### Other methods
```python
import tranzlate
google = tranzlate.Translator("google")
bing = tranzlate.Translator("bing")
```
#### Get supported languages
Get a list of all supported (source) languages by the translator's engine:
```python
print(google.supported_languages)
```
#### Check if a language is supported
Check if a (source) language is supported by the translator's engine:
```python
is_supported = google.supports_language('yo')
print(is_supported)
# Output: True
```
#### Check if a language pair is supported
Check if a language pair is supported by the translator's engine:
```python
is_supported = bing.supports_pair(src_lang='en', target_lang='yo')
print(is_supported)
# Output: True
```
#### Get a list of supported target languages for a source language
Get a list of supported target languages for a source language:
```python
supported_target_languages = bing.get_supported_target_languages('en')
print(supported_target_languages)
```
### Testing
To run tests, simply run the following command in the root directory of your cloned repository:
```bash
python -m unittest discover tests "test_*.py"
```
### Contributing
Contributions are welcome. Please open an issue or submit a pull request.
Raw data
{
"_id": null,
"home_page": null,
"name": "tranzlate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "ti-oluwa <tioluwa.dev@gmail.com>",
"keywords": "translate, translation, google translate, bing translate, translate text, translate files, translate markup, translate html, translate xml, beautifulsoup4, detect language",
"author": null,
"author_email": "ti-oluwa <tioluwa.dev@gmail.com>",
"download_url": null,
"platform": null,
"description": "## tranzlate\n\nA wrapper around the [`translators`](https://pypi.org/project/translators/) package, providing a simpler interface for the translation of text, files, markup and BeautifulSoup.\n\n## Installation\n\nPerform a quick install with pip:\n\n```bash\npip install tranzlate\n```\n\n## Usage\n\n> Ensure you have `beautifulsoup4` installed if you want to translate markup or BeautifulSoup. Run `pip install beautifulsoup4` in your terminal.\n\n### Create a translator\n\nThe `Translator` class is the main interface for the package. It can be used to translate text, bytes, files, markup and BeautifulSoup. To create an instance of the `Translator` class, simply import the `tranzlate` package and instantiate a `Translator`:\n\n```python\nimport tranzlate\n\ntranslator = tranzlate.Translator()\n```\n\n### Use a custom translation engine\n\nBy default, the `Translator` class uses Bing Translator as its translation engine. Based on test results, Bing is the most reliable translation engine. However, you can use any translation engine that is supported by the translators package by passing the name of the engine to the `Translator` class on instantiation:\n\nIn this example, we will use Google Translate as our translation engine:\n\n```python\nimport tranzlate\n\ngoogle = tranzlate.Translator('google')\n```\n\nTo get a list of all supported translation engines:\n\n```python\nimport tranzlate\n\nprint(tranzlate.Translator.engines())\n\n# Output:\n# ['bing', 'google', 'yandex', 'baidu', 'sogou', 'tencent', 'deepl', 'alibaba', ...]\n```\n\n### Detect language\n\n```python\nimport tranzlate\n\ntext = 'Good Morning!'\nlanguage = tranzlate.Translator.detect_language(text)\nprint(language)\n\n# Output: en\n```\n\n### Translate text, bytes, markup and BeautifulSoup\n\nTranslate text, markup or a soup using the `translate` method of the `Translator` class. The `translate` method is a general purpose method that can be used to translate text, bytes and markup.\n\n#### Translate text/bytes\n\n```python\nimport tranzlate\n\nbing = tranzlate.Translator(\"bing\")\ntext = 'Good Morning!'\ntranslation = bing.translate(text, target_lang='yo')\nprint(translation)\n\n# Output: Eku ojumo!\n```\n\n#### Translate markup\n\n```python\nimport tranzlate\n\nbing = tranzlate.Translator(\"bing\")\n\nmarkup = '<p>Good Morning!</p>'\ntranslated_markup = bing.translate(markup, target_lang='yo', is_markup=True)\nprint(translated_markup)\n\n# Output: <p>Eku ojumo!</p>\n```\n\n#### Translate BeautifulSoup\n\n```python\nimport tranzlate\nfrom bs4 import BeautifulSoup\n\nbaidu = tranzlate.Translator(\"baidu\")\nmarkup = '<p>Good Morning!</p>'\nsoup = BeautifulSoup(markup, 'html.parser')\ntranslated_soup = baidu.translate_soup(soup, target_lang='fr')\n```\n\nHowever, there are specialized methods for translating text, markup and BeautifulSoup objects. These methods are `translate_text`, `translate_markup` and `translate_soup` respectively.\n\n### Translate files\n\nTo translate files, we use the `translate_file` method.\n\n```python\nimport tranzlate\n\nbing = tranzlate.Translator() # Bing is used by default\ntranslated_file = bing.translate_file('path/to/file.txt', src_lang=\"en\", target_lang='yo')\n```\n\nIt is advisable to specify the source language when performing translations as it helps the translation engine to provide more accurate translations.\n\n### Use a proxy\n\nTo use a proxy, simply pass your proxies on translation:\n\n```python\nimport tranzlate\n\ndeepl = tranzlate.Translator(\"deepl\")\ntext = 'Good Morning!'\ntranslation = deepl.translate(text, target_lang='yo', proxies={'https': 'https://<proxy>:<port>'})\nprint(translation)\n```\n\n### Other methods\n\n```python\nimport tranzlate\n\ngoogle = tranzlate.Translator(\"google\")\nbing = tranzlate.Translator(\"bing\")\n```\n\n#### Get supported languages\n\nGet a list of all supported (source) languages by the translator's engine:\n\n```python\nprint(google.supported_languages)\n```\n\n#### Check if a language is supported\n\nCheck if a (source) language is supported by the translator's engine:\n\n```python\nis_supported = google.supports_language('yo')\nprint(is_supported)\n\n# Output: True\n```\n\n#### Check if a language pair is supported\n\nCheck if a language pair is supported by the translator's engine:\n\n```python\nis_supported = bing.supports_pair(src_lang='en', target_lang='yo')\nprint(is_supported)\n\n# Output: True\n```\n\n#### Get a list of supported target languages for a source language\n\nGet a list of supported target languages for a source language:\n\n```python\nsupported_target_languages = bing.get_supported_target_languages('en')\nprint(supported_target_languages)\n```\n\n### Testing\n\nTo run tests, simply run the following command in the root directory of your cloned repository:\n\n```bash\npython -m unittest discover tests \"test_*.py\"\n```\n\n### Contributing\n\nContributions are welcome. Please open an issue or submit a pull request.\n",
"bugtrack_url": null,
"license": null,
"summary": "Translate text, files, markup and BeautifulSoup.",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/ti-oluwa/tranzlate/issues",
"Homepage": "https://github.com/ti-oluwa/tranzlate",
"Repository": "https://github.com/ti-oluwa/tranzlate"
},
"split_keywords": [
"translate",
" translation",
" google translate",
" bing translate",
" translate text",
" translate files",
" translate markup",
" translate html",
" translate xml",
" beautifulsoup4",
" detect language"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "06243c36da102cea49813511ae51914ac5403cf1139ddc4f11fdd1dd6679c2c4",
"md5": "41c6e3f8be517090a3df776eafbb0709",
"sha256": "01e5da477fdbedcf3a94d5c4447276a37429215082a55a9eaefd714c0a5a2ee0"
},
"downloads": -1,
"filename": "tranzlate-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "41c6e3f8be517090a3df776eafbb0709",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9463,
"upload_time": "2024-08-17T10:26:34",
"upload_time_iso_8601": "2024-08-17T10:26:34.088851Z",
"url": "https://files.pythonhosted.org/packages/06/24/3c36da102cea49813511ae51914ac5403cf1139ddc4f11fdd1dd6679c2c4/tranzlate-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-17 10:26:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ti-oluwa",
"github_project": "tranzlate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "tranzlate"
}
JSON
