{"id":17469767,"url":"https://github.com/bikatr7/easytl","last_synced_at":"2025-04-21T09:05:17.270Z","repository":{"id":222492665,"uuid":"757466492","full_name":"Bikatr7/EasyTL","owner":"Bikatr7","description":"Seamless Multi-API Translation: Simplifying Language Barriers with DeepL, OpenAI, Gemini, Google Translate and More!","archived":false,"fork":false,"pushed_at":"2025-03-20T21:33:43.000Z","size":616,"stargazers_count":10,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-20T00:54:08.619Z","etag":null,"topics":["anthropic","deepl","google-translate","language-translation","machine-translation","microsoft-azure","multi-api","openai","python","translation","wrapper-library"],"latest_commit_sha":null,"homepage":"https://easytl.readthedocs.io/en/latest/index.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bikatr7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-14T14:55:57.000Z","updated_at":"2025-04-03T13:40:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"4df54796-f0da-4173-be42-151b6abc8594","html_url":"https://github.com/Bikatr7/EasyTL","commit_stats":null,"previous_names":["bikatr7/easytl"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikatr7%2FEasyTL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikatr7%2FEasyTL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikatr7%2FEasyTL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikatr7%2FEasyTL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bikatr7","download_url":"https://codeload.github.com/Bikatr7/EasyTL/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249834786,"owners_count":21331988,"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":["anthropic","deepl","google-translate","language-translation","machine-translation","microsoft-azure","multi-api","openai","python","translation","wrapper-library"],"created_at":"2024-10-18T15:43:43.831Z","updated_at":"2025-04-20T00:54:26.836Z","avatar_url":"https://github.com/Bikatr7.png","language":"Python","readme":"---------------------------------------------------------------------------------------------------------------------------------------------------\n**Table of Contents**\n\n- [**Notes**](#notes)\n- [**Quick Start**](#quick-start)\n- [**Installation**](#installation)\n- [**Features**](#features)\n- [**API Usage**](#api-usage)\n  - [Translating Text](#translating-text)\n  - [Generic Translation Methods](#generic-translation-methods)\n  - [Cost Calculation](#cost-calculation)\n  - [Credentials Management](#credentials-management)\n- [**License**](#license)\n- [**Contact**](#contact)\n- [**Contribution**](#contribution)\n- [**Acknowledgements**](#acknowledgements)\n\n--------------------------------------------------------------------------------------------------------------------------------------------------\n\n## **Notes**\u003ca name=\"notes\"\u003e\u003c/a\u003e\n\nSeamless Multi-API Translation: Simplifying Language Barriers with DeepL, OpenAI, Gemini, Google Translate and More! \n\nEasyTL allows for the overriding of the default base URL for the OpenAI API. This is useful for services like OpenRouter that are compatible with the OpenAI API to use custom LLMs not explicitly supported by EasyTL.\n\nEasyTL has a [Trello board](https://trello.com/b/Td555CoW/easytl) for tracking planned features and issues:\n\nWe've compiled a repository of examples and use cases for EasyTL at this [GitHub repository](https://github.com/Bikatr7/easytl-demo)\n\n\u003e [!TIP]\n\u003e You can find the full documentation [here](https://easytl.readthedocs.io/en/latest/index.html)! (work in progress)\n\nEasyTL tends to update it's LLM internal dependencies at least once a month, this will result in at least one minor version update per month. This is to ensure that the package is up to date with the latest features and bug fixes from the LLM services.\n\nSometimes this will occur faster, if a critical bug is found or a new feature is added that is important to the package.\n\n---------------------------------------------------------------------------------------------------------------------------------------------------\n## **Quick Start**\u003ca name=\"quick-start\"\u003e\u003c/a\u003e\n\nTo get started with EasyTL, install the package via pip:\n\n```bash\npip install easytl\n```\n\nThen, you can translate text using by importing the global client.\n\nFor example, with DeepL:\n\n```python\nfrom easytl import EasyTL\n\n## Set your API key\nEasyTL.set_credentials(\"deepl\", \"YOUR_API_KEY\")\n\n## You can also validate your API keys; translation functions will do this automatically\nis_valid, e = EasyTL.test_credentials(\"deepl\")\n\ntranslated_text = EasyTL.deepl_translate(\"私は日本語が話せます\", \"EN-US\") ## Text to translate, language to translate to, only two \"required\" arguments but there are more optional arguments for additional functionality and other services.\n\nprint(translated_text) ## Output: \"I can speak Japanese\"\n```\n\nor with OpenAI:\n\n```python\nfrom easytl import EasyTL\n\nimport asyncio\n\nasync def main():\n\n    ## Set your API key\n    EasyTL.set_credentials(\"openai\", \"YOUR_API_KEY\")\n\n    ## Get's the raw response from the API, allowing you to access the full response object\n    raw_response = await EasyTL.openai_translate_async(\"I can speak Japanese\", model=\"gpt-4o\", translation_instructions=\"Translate this text to Japanese.\", response_type=\"raw\") \n\n    print(raw_response.choices[0].message.content) ## Output: \"私は日本語が話せます\" or something similar\n\nif(__name__ == \"__main__\"):\n    asyncio.run(main())\n\n```\n\n---------------------------------------------------------------------------------------------------------------------------------------------------\n\n## **Installation**\u003ca name=\"installation\"\u003e\u003c/a\u003e\n\nPython 3.10+\n\nEasyTL can be installed using pip:\n\n```bash\npip install easytl\n```\n\nThis will install EasyTL along with its dependencies and requirements.\n\nThese are the dependencies/requirements that will be installed:\n```bash\nsetuptools\u003e=61.0\nwheel\nsetuptools_scm\u003e=6.0\ntomli\ngoogle-generativeai\u003e=0.8.3\ndeepl\u003e=1.20.0\nopenai\u003e=1.58.1\nbackoff\u003e=2.2.1\ntiktoken\u003e=0.7.0\ngoogle-cloud-translate\u003e=3.15.3\nanthropic\u003e=0.42.0\nrequests\u003e=2.31.0\npydantic\n```\n---------------------------------------------------------------------------------------------------------------------------------------------------\n\n## **Features**\u003ca name=\"features\"\u003e\u003c/a\u003e\n\nEasyTL offers seamless integration with several translation APIs, allowing users to easily switch between services based on their needs. Key features include:\n\n- Support for multiple translation APIs including OpenAI, DeepL, Gemini, Google Translate, Microsoft Azure Translate, and Anthropic.\n- Simple API key and credential management and validation.\n- Cost estimation tools to help manage usage based on text length, translation instructions for LLMs, and translation services.\n- Highly customizable translation options, with each API's original features and more. \n- Lots of optional arguments for additional functionality. Such as decorators, semaphores, and rate-limit delays.\n\n---------------------------------------------------------------------------------------------------------------------------------------------------\n\n## **API Usage**\u003ca name=\"api-usage\"\u003e\u003c/a\u003e\n\n### Translating Text\n\nTranslate functions can be broken down into two categories: LLM and non-LLM. LLM ones can take instructions, while non-LLM ones require a target language. \n\n`deepl_translate`, `googletl_translate`, and `azure_translate` are non-LLM functions, while `openai_translate`, `gemini_translate`, and `anthropic_translate` are LLM functions.\n\nEach method accepts various parameters to customize the translation process, such as language, text format, and API-specific features like formality level or temperature. However these vary wildly between services, so it is recommended to check the documentation for each service for more information.\n\nAll services offer asynchronous translation methods that return a future object for concurrent processing. These methods are suffixed with `_async` and can be awaited to retrieve the translated text.\n\nInstead of receiving the translated text directly, you can also use the `response_type` parameter to get the raw response object, specify a json response where available, or both.\n  \n  `text` - Default. Returns the translated text.\n\n  `json` - Returns the response as a JSON object. Not all services support this.\n\n  `raw` - Returns the raw response object from the API. This can be useful for accessing additional information or debugging.\n  \n  `raw_json` - Returns the raw response object with the text but with the response also a json object. Again, not all services support this.\n\n### Generic Translation Methods\n\nEasyTL has generic translation methods `translate` and `translate_async` that can be used to translate text with any of the supported services. These methods accept the text, service, and kwargs of the respective service as parameters.\n\n### Cost Calculation\n\nThe `calculate_cost` method provides an estimate of the cost associated with translating a given text with specified settings for each supported service.\n\nThese are characters or tokens depending on the type of translate function used.\n\n```python\nnum_characters, cost, model = EasyTL.calculate_cost(\"This has a lot of characters\", \"deepl\")\n```\n\nor \n\n```python\nnum_tokens, cost, model = EasyTL.calculate_cost(\"This has a lot of tokens.\", \"openai\", model=\"gpt-4\", translation_instructions=\"Translate this text to Japanese.\")\n```\n\n### Credentials Management\n\nCredentials can be set and validated using `set_credentials` and `test_credentials` methods to ensure they are active and correct before submitting translation requests.\n\nIf you don't provide an api key, the package will attempt to read it from the environment variables. The format for this is as follows:\n\n```python\n\n# This is a dictionary mapping the service names to their respective environment variables.\nenvironment_map = \n{\n  # DeepL translation service\n  \"deepl\": \"DEEPL_API_KEY\",\n  \n  # Gemini translation service\n  \"gemini\": \"GEMINI_API_KEY\",\n  \n  # OpenAI translation service\n  \"openai\": \"OPENAI_API_KEY\",\n  \n  # Google Translate service\n  \"google translate\": \"PATH_TO_GOOGLE_CREDENTIALS_JSON\",\n  \n  # Anthropic translation service\n  \"anthropic\": \"ANTHROPIC_API_KEY\",\n}\n\n```\n\n---------------------------------------------------------------------------------------------------------------------------------------------------\n\n## **License**\u003ca name=\"license\"\u003e\u003c/a\u003e\n\nThis project, EasyTL, is licensed under the GNU Lesser General Public License v2.1 (LGPLv2.1) - see the LICENSE file for complete details.\n\nThe LGPL is a permissive copyleft license that enables this software to be freely used, modified, and distributed. It is particularly designed for libraries, allowing them to be included in both open source and proprietary software. When using or modifying EasyTL, you can choose to release your work under the LGPLv2.1 to contribute back to the community or incorporate it into proprietary software as per the license's permissions.\n\n---------------------------------------------------------------------------------------------------------------------------------------------------\n\n## **Contact**\u003ca name=\"contact\"\u003e\u003c/a\u003e\n\nIf you have any questions or suggestions, feel free to reach out to me at [Bikatr7@proton.me](mailto:Bikatr7@proton.me)\n\nAlso feel free to check out the [GitHub repository](https://github.com/Bikatr7/EasyTL) for this project.\n\nOr the issue tracker [here](https://github.com/Bikatr7/EasyTL/issues).\n\n---------------------------------------------------------------------------------------------------------------------------------------------------\n\n## **Contribution**\u003ca name=\"contribution\"\u003e\u003c/a\u003e\n\nContributions are welcome! I don't have a specific format for contributions, but please feel free to submit a pull request or open an issue if you have any suggestions or improvements.\n\n---------------------------------------------------------------------------------------------------------------------------------------------------\n\n## **Acknowledgements**\u003ca name=\"acknowledgements\"\u003e\u003c/a\u003e\n\nEasyTL was originally developed as a part of [Kudasai](https://github.com/Bikatr7/Kudasai), a Japanese preprocessor later turned Machine Translator. It was later split off into its own package to be used independently of Kudasai for multiple reasons.\n\nThis package is also my second serious attempt at creating a Python package, so I'm sure there are some things that could be improved. Feedback is welcomed.\n\n---------------------------------------------------------------------------------------------------------------------------------------------------\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbikatr7%2Feasytl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbikatr7%2Feasytl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbikatr7%2Feasytl/lists"}