{"id":19179601,"url":"https://github.com/animenosekai/translate","last_synced_at":"2025-05-15T23:03:07.701Z","repository":{"id":37942875,"uuid":"335014446","full_name":"Animenosekai/translate","owner":"Animenosekai","description":"A module grouping multiple translation APIs","archived":false,"fork":false,"pushed_at":"2024-07-10T07:07:10.000Z","size":10417,"stargazers_count":544,"open_issues_count":18,"forks_count":61,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-15T23:02:00.956Z","etag":null,"topics":["bing-translate","deepl","google-translate","language","python","reverso","translate","translation","translator","yandex","yandex-translate"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Animenosekai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-01T16:36:00.000Z","updated_at":"2025-05-14T16:16:50.000Z","dependencies_parsed_at":"2023-10-15T16:48:40.382Z","dependency_job_id":"f20ea73f-cc12-47d0-a967-ef3d1245c91f","html_url":"https://github.com/Animenosekai/translate","commit_stats":{"total_commits":246,"total_committers":7,"mean_commits":"35.142857142857146","dds":"0.18292682926829273","last_synced_commit":"18e008aa505387e9334ca7a985f21a6c0dd3f7f8"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Animenosekai%2Ftranslate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Animenosekai%2Ftranslate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Animenosekai%2Ftranslate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Animenosekai%2Ftranslate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Animenosekai","download_url":"https://codeload.github.com/Animenosekai/translate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436944,"owners_count":22070946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bing-translate","deepl","google-translate","language","python","reverso","translate","translation","translator","yandex","yandex-translate"],"created_at":"2024-11-09T10:43:36.720Z","updated_at":"2025-05-15T23:03:07.675Z","avatar_url":"https://github.com/Animenosekai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `translatepy` (originally: translate)\n\n### An aggregation of multiple translation API\n\n***Translate, transliterate, get the language of texts in no time with the help of multiple APIs!***\n\n[![PyPI version](https://badge.fury.io/py/translatepy.svg)](https://pypi.org/project/translatepy/)\n[![Downloads](https://static.pepy.tech/personalized-badge/translatepy?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=Total%20Downloads)](https://pepy.tech/project/translatepy)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/translatepy)](https://pypistats.org/packages/translatepy)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/translatepy)](https://pypi.org/project/translatepy/)\n[![PyPI - Status](https://img.shields.io/pypi/status/translatepy)](https://pypi.org/project/translatepy/)\n[![GitHub - License](https://img.shields.io/github/license/Animenosekai/translate)](https://github.com/Animenosekai/translate/blob/master/LICENSE)\n[![GitHub top language](https://img.shields.io/github/languages/top/Animenosekai/translate)](https://github.com/Animenosekai/translate)\n[![CodeQL Checks Badge](https://github.com/Animenosekai/translate/workflows/CodeQL%20Python%20Analysis/badge.svg)](https://github.com/Animenosekai/translate/actions?query=workflow%3ACodeQL)\n[![Pytest](https://github.com/Animenosekai/translate/actions/workflows/pytest.yml/badge.svg)](https://github.com/Animenosekai/translate/actions/workflows/pytest.yml)\n![Code Size](https://img.shields.io/github/languages/code-size/Animenosekai/translate)\n![Repo Size](https://img.shields.io/github/repo-size/Animenosekai/translate)\n![Issues](https://img.shields.io/github/issues/Animenosekai/translate)\n\n## Getting Started\n\nThese instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.\n\n### Prerequisites\n\nYou will need Python 3 to use this module\n\n```bash\n# vermin output\nMinimum required versions: 3.2\nIncompatible versions:     2\n```\n\nAccording to Vermin (`--backport typing`), Python 3.2 is needed for the backport of typing but some may say that it is available for python versions higher than 3.0\n\nAlways check if your Python version works with `translatepy` before using it in production\n\n## Installing\n\n### Option 1: From PyPI\n\n```bash\npip install --upgrade translatepy\n```\n\n### Option 2: From Git\n\n```bash\npip install --upgrade git+https://github.com/Animenosekai/translate\n```\n\nYou can check if you successfully installed it by printing out its version:\n\n```bash\n$ translatepy --version\n# output:\ntranslatepy v2.3\n```\n\nor just:\n\n```bash\n$ python -c \"import translatepy; print(translatepy.__version__)\"\n# output:\ntranslatepy v2.3\n```\n\n## List of Built-in Services\n\n- [Microsoft Bing Translator](https://www.bing.com/translator)\n- [DeepL](https://www.deepl.com/translator)\n- [Google Translate](https://translate.google.com)\n- [LibreTranslate](https://libretranslate.com)\n- [Microsoft Translator](http://translator.microsoft.com/)\n- [MyMemory](https://mymemory.translated.net)\n- [Reverso](https://www.reverso.net/text_translation.aspx)\n- [Translate.com](https://www.translate.com)\n- [Yandex Translate](https://translate.yandex.com)\n\n... but plugins can be made and/or used. More on that in the [plugins](#plugins) section.\n\n\u003e All of the names belong to their respective rightholders.\n\n## Usage\n\n### Command line interface mode\n\n#### Interactive Shell (REPL)\n\n```bash\n$ translatepy shell\n## Choose the action\n[?] What do you want to do?: Translate\n \u003e Translate\n   Transliterate\n   Spellcheck\n   Language\n   Example\n   Quit\n\n## Choose the language to translate in (this step can be skipped by passing the `--dest-lang` argument when starting the program)\nIn what language do you want to translate in?\n[?] (translatepy ~ Select Lang.) \u003e : ...\n\n## Translate\nEnter '.quit' to stop translating\n(translatepy ~ Translate) \u003e ... # type in whatever you want to translate\n```\n\n#### In other applications/from the terminal\n\nSelect an action:\n{translate,transliterate,language,spellcheck}\n\nand pass it as a command with the right arguments:\n\n```bash\n$ translatepy translate --dest-lang Français --text Hello\n{\n    \"success\": true,\n    \"service\": \"Google\",\n    \"source\": \"Hello\",\n    \"sourceLanguage\": \"eng\",\n    \"destinationLanguage\": \"fra\",\n    \"result\": \"Bonjour\"\n}\n```\n\n### In Python script\n\n#### The Translator Class\n\nThe translator lets you group and use multiple translators at the same time, to increase your chance on getting an answer.\n\nIt takes two *optional* arguments: the `services_list` argument, which is a list of `Translator` objects and the second one being the `request` argument which is the object which will be used to make requests.\n\nIt has all of the supported methods.\n\n- translate: To translate things\n- translate_html : To translate HTML snippets\n- transliterate: To transliterate things\n- spellcheck: To check the spelling of a text\n- language: To get the language of a text\n- example: To get a list of examples of a word\n- dictionary: To get a list of translations categorized into \"featured\" and \"less common\" by DeepL and Linguee\n- text_to_speech: To get an audio file containing the speech version of the given text\n\nWhen something goes wrong or nothing got found, an exception **will** be raised. *(this is in bold because it is one of the difference that comes with `v2`)*\n\n```python\n\u003e\u003e\u003e from translatepy import Translator\n\u003e\u003e\u003e translator = Translator()\n\u003e\u003e\u003e translator.translate(\"Hello\", \"French\")\nTranslationResult(service=Yandex, source=Hello, source_language=auto, destination_language=French, result=Bonjour)\n\u003e\u003e\u003e translator.language(\"こんにちは\")\nLanguageResult(service=Yandex, source=こんにちは, result=Language(jpn))\n```\n\n#### Translators\n\nYou can use each translators separately by using them the same way as you would with `translatepy.Translator` (or `translatepy.Translate`)\n\n```python\n\u003e\u003e\u003e from translatepy.translators.google import GoogleTranslate\n\u003e\u003e\u003e gtranslate = GoogleTranslate()\n\u003e\u003e\u003e gtranslate.translate(\"Hello World\", \"Japanese\")\nTranslationResult(service=Google, source=Hello World, source_language=eng, destination_language=jpn, result=こんにちは世界)\n```\n\nAnd some translators have their own parameters:\n\n```python\n\u003e\u003e\u003e gtranslate_china = GoogleTranslate(service_url=\"translate.google.cn\")\n\u003e\u003e\u003e gtranslate_china.translate(\"Hello World\", \"Japanese\")\nTranslationResult(service=Google, source=Hello World, source_language=eng, destination_language=jpn, result=こんにちは世界)\n\n# it can even be used by translatepy.Translator\n\u003e\u003e\u003e from translatepy import Translator\n\u003e\u003e\u003e t = Translator([gtranslate_china])\n\u003e\u003e\u003e t.translate(\"Hello World\", \"Japanese\")\nTranslationResult(service=Google, source=Hello World, source_language=eng, destination_language=jpn, result=こんにちは世界)\n```\n\n#### The Language Class\n\nThe language class contains lots of information about a language.\n\nYou need to pass the language name or code to the class initialization:\n\n```python\n\u003e\u003e\u003e from translatepy import Language\n\u003e\u003e\u003e Language(\"French\")\n# Returns a Language class with the \"fra\" language\n\u003e\u003e\u003e Language(\"en\")\n# Returns a Language class with the \"eng\" language\n\u003e\u003e\u003e Language(\"eng\")\n# Returns a Language class with the \"eng\" language\n\u003e\u003e\u003e Language(\"日本語\")\n# Returns a Language class with the \"jpn\" language\n```\n\nThe Language Class contains both the ISO 639-1 Alpha-2 language code and the ISO 639-2 Alpha-3 language code.\n\n```python\n\u003e\u003e\u003e Language(\"English\").alpha2 # ISO 639-1 (alpha 2), nullable\n'en'\n\u003e\u003e\u003e Language(\"English\").alpha3 # ISO 639-3 (alpha 3)\n'eng'\n\u003e\u003e\u003e Language(\"English\").alpha3b # ISO 639-2B, nullable\n'eng'\n\u003e\u003e\u003e Language(\"English\").alpha3t # ISO 639-2T, nullable\n'eng'\n```\n\nEach available language has its own ID, coming from the Alpha-3 Language Code most of the times (but which is also unique for languages such as the \"Automatic\" Language and the \"Emoji\" one)\n\n```python\n\u003e\u003e\u003e Language(\"French\").id\n'fra'\n\u003e\u003e\u003e Language(\"Emoji\").id\n'emj'\n\u003e\u003e\u003e Language(\"Automatic\").id\n'auto'\n```\n\nIt also contains the language name for a lot of languages:\n\n```python\n\u003e\u003e\u003e Language(\"Français\").in_foreign_languages.get(\"ja\", None) # an alpha-2 code needs to be passed in, also make sure to have a fallback such as None here because not all of the languages had been translated.\n'フランス語'\n```\n\nAll of the languages which have an `alpha2` code are assured to have at least their translation in all of the following languages:\n\n```python\nto = ['af', 'am', 'ar', 'az', 'be', 'bg', 'bn', 'bs', 'ca', 'ceb', 'co', 'cs', 'cy', 'da', 'de', 'el', 'eo', 'es', 'et', 'eu', 'fa', 'fi', 'fr', 'fy', 'ga', 'gd', 'gl', 'gu', 'ha', 'haw', 'hi', 'hmn', 'hr', 'ht', 'hu', 'hy', 'id', 'ig', 'is', 'it', 'he', 'ja', 'jv', 'ka', 'kk', 'km', 'kn', 'ko', 'ku', 'ky', 'la', 'lb', 'lo', 'lt', 'lv', 'mg', 'mi', 'mk', 'ml', 'mn', 'mr', 'ms', 'mt', 'my', 'ne', 'nl', 'no', 'ny', 'or', 'pa', 'pl', 'ps', 'pt', 'ro', 'ru', 'sd', 'si', 'sk', 'sl', 'sm', 'sn', 'so', 'sq', 'sr', 'st', 'su', 'sv', 'sw', 'ta', 'te', 'tg', 'th', 'tl', 'tr', 'ug', 'uk', 'ur', 'uz', 'vi', 'xh', 'yi', 'yo', 'zh', 'zu']\n```\n\nThe other ones may or may not have a translation in more or less languages.\n\nThe Language class also contains the \"similarity\" attribute which gives back a number between 0 and 100 which shows the similarity of the input language with what it found in the language code database:\n\n```python\n\u003e\u003e\u003e round(Language(\"French\").similarity, 2)\n100.0\n\u003e\u003e\u003e Language(\"Englesh\").similarity\n94.86832980505137\n```\n\n\u003cdetails\u003e\n    \u003csummary\u003eNote\u003c/summary\u003e\n    \u003cp\u003eOnly the languages which have an \u003ci\u003ealpha2\u003c/i\u003e language code and are of type \u003ci\u003eLiving\u003c/i\u003e or \u003ci\u003eAncient\u003c/i\u003e are vectorized and will be used in the similarity search.\u003c/p\u003e\n\u003c/details\u003e\n\u003cbr\u003e\n\nEach language also have 'extra' data: their type *(nullable)* and the scope *(nullable)*.\n\n```python\n\u003e\u003e\u003e Language(\"French\").extra\nLanguageExtra(type=LanguageType(Living), scope=LanguageScope(Individual))\n\u003e\u003e\u003e Language(\"Latin\").extra.type\nLanguageType(Ancient)\n```\n\nA `translatepy.exceptions.UnknownLanguage` exception is raised if the given language is unknown.\n\nThis exception contains the most similar language along with its similarity:\n\n```python\n\u003e\u003e\u003e from translatepy import Language\n\u003e\u003e\u003e from translatepy.exceptions import UnknownLanguage\n\u003e\u003e\u003e try:\n...     language = Language(\"中国\")\n... except UnknownLanguage as error:\n...     print(\"The similarity seemed to be too low for translatepy to accept it as a correct language name\")\n...     print(\"The language found is:\", error.guessed_language)\n...     print(\"Its similarity from the passed input is:\", str(error.similarity))\n```\n\n\u003e If you find that the default threshold given to the language search is too low, you can always change it by passing the `threshold` parameter when initializing a `Language`:\n\n```python\n\u003e\u003e\u003e from translatepy import Language\n\u003e\u003e\u003e Language(\"国語\")\nTraceback (most recent call last):\n  File \"\u003cstdin\u003e\", line 1, in \u003cmodule\u003e\n  File \"/Users/animenosekai/Documents/Coding/Projects/translate/translatepy/language.py\", line 106, in __init__\n    raise UnknownLanguage(_search_result, self.similarity, raising_message)\ntranslatepy.exceptions.UnknownLanguage: Couldn't recognize the given language (中国)\nDid you mean: 中国語 (Similarity: 81.65%)?\n\u003e\u003e\u003e Language(\"中国\", threshold=80)\nLanguage(zho)\n```\n\n### Results\n\nAll of the methods should have its own result class (defined in [translatepy/models.py](translatepy/models.py)) which all have at least the service, source, result attributes and a \"as_json\" method to convert everything into a JSON String.\n\n### Errors\n\nAll of the `translatepy` errors are inherited from `translatepy.exceptions.TranslatepyException` so that you can easily catch a `translatepy` error.\n\n```python\n\u003e\u003e\u003e from translatepy import Translator\n\u003e\u003e\u003e from translatepy.exceptions import TranslatepyException, UnknownLanguage\n\u003e\u003e\u003e t = Translator()\n\u003e\u003e\u003e def translate(text, dest):\n...     try:\n...         result = t.translate(text, destination_language=dest)\n        except UnknownLanguage as err:\n            print(\"An error occured while searching for the language you passed in\")\n            print(\"Similarity:\", round(err.similarity), \"%\")\n            return\n        except TranslatepyException:\n            print(\"An error occured while translating with translatepy\")\n            return\n        except Exception:\n            print(\"An unknown error occured\")\n            return\n...     # do something with the result...\n...     \n```\n\n### Plugins\n\nYou can make your own `Translator` using the `translatepy.translators.base.BaseTranslator` class.\n\nMake sure that you inherit from this class when creating your translator and to **follow the instruction from [plugin.md](https://github.com/Animenosekai/translate/blob/main/plugin.md)**\n\n## Caching\n\nAll of the operations are cached to provide the best performances\n\nYou can empty the cache by calling the method \"`clean_cache`\"\n\n## Deployment\n\nThis module is currently in development and might contain bugs.\n\nFeel free to use it in production if you feel like it is suitable for your production even if you may encounter issues.\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an discussion first to discuss what you would like to change.\n\nPlease make sure to update the tests as appropriate.\n\n## Built With\n\n- [pyuseragents](https://github.com/Animenosekai/useragents) - To generate the \"User-Agent\" HTTP header\n- [requests](https://github.com/psf/requests) - To make HTTP requests\n- [beautifulsoup4](https://pypi.org/project/beautifulsoup4/) - To parse HTML\n- [inquirer](https://github.com/magmax/python-inquirer) - To make beautiful CLIs\n\n## Authors\n\n- **Anime no Sekai** - *Initial work* - [Animenosekai](https://github.com/Animenosekai)\n- **Zhymabek Roman** - *Major Contributor (PR #10, PR #15)* - [ZhymabekRoman](https://github.com/ZhymabekRoman)\n\n## Disclaimer\n\nPlease **do not** use this module in a commercial manner. Pay a proper API Key from one of the services to do so.\n\n## License\n\nThis project is licensed under the GNU Affero General Public License v3.0 License - see the [LICENSE](LICENSE) file for details\n\n### Dataset\n\nThe 'playground' folder contains a lot of our search and results for the language management on `translatepy` (this folder might be very messy because of all of our experiments in it)\n\nThe `translatepy/utils/_language_cache.py` file contains all of the data for the language searching used by `translatepy`\n\nPlease ask us if you want to use them in another project.\n\nMost of the language data come from [Google Translate](http://translate.google.com), [Yandex Translate](http://translate.yandex.com) and [`iso-639-3`](https://github.com/wooorm/iso-639-3)\n\n## Acknowledgments\n\n- Thanks to @spamz23 (Diogo Silva) for the development of the code refactoring used in v2 (tests and `Translator`) (check: [spamz23/translate](https://github.com/spamz23/translate))\n- Thanks to @ZhymabekRoman (Zhymabek Roman) for working on making Yandex more stable and on the v2!\n- Inspired by py-googletrans (by @ssut) (especially the thread: [Issue #268](https://github.com/ssut/py-googletrans/issues/268))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanimenosekai%2Ftranslate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanimenosekai%2Ftranslate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanimenosekai%2Ftranslate/lists"}