Merge pull request #115 from justiamtgm/master

terryyin · web-flow · commit f3bd689c14cc · 2025-11-03T12:29:59.000+09:00
QoL fixes &amp; Updated Wiki &amp; Tried to implement new Yandex Provider
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,23 @@
+﻿# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
+        
diff --git a/README.rst b/README.rst
@@ -13,7 +13,7 @@ Translated MyMemory API, LibreTranslate, and DeepL's free and pro APIs
 Why Should I Use This?
 ----------------------
 
-The biggest reason to use translate is to  make translations in a simple way without the need of bigger
+The biggest reason to use translate is to make translations in a simple way without the need of bigger
 effort and can be used as a translation tool like command line
 
 
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -1,6 +1,18 @@
 Overview
 ========
 
-Translate is a simple but powerful translation tool written in python with with support for multiple translation providers. It can be used as python module or as command line tool
+Translate is a simple but powerful translation tool written in python with with support for multiple translation providers. By now we offer integration with Microsoft Translation API, Translated MyMemory API, LibreTranslate, and DeepL's free and pro APIs.
+
+The biggest reason to use translate is to make translations in a simple way without the need of bigger effort and can be used as a translation tool like command line.
+
+Features:
+-----
+
+* Translate your output in real time
+* Do translation in your terminal using the command line
+* Support of many APIs
+* Open-source code on `GitHub <https://github.com/terryyin/translate-python>`_
+
+
+
 
-TODO: Add more content
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
@@ -82,11 +82,26 @@ or run the command line and follow the steps:
     Secret Access Key []:
 
 
-The country code, as far as I know, is following https://en.wikipedia.org/wiki/ISO_639-1.
+The country code is following https://en.wikipedia.org/wiki/ISO_639-1.
 
 Use As A Python Module
 ----------------------
+You can use translate as a Python module, imported in the code. Function could use following parameters:
 
+::
+
+   Translator(from_lang="fr", to_lang="it", provider="deepl", secret_access_key="TOKEN", region="westeurope")
+
+   Options:
+      from_lang                 Language, you are going to translate from. Could be any ISO 639-1 country code, the default value is "autodetect". (optional)
+      to_lang                   Language, you are going to translate into. Could be any ISO 639-1 country code.
+      provider                  API translator used to make translation, could be any of listed in providers.rst (optional)
+      secret_access_key         Secret token, used by some APIs. (optional)
+      region                    API region, used by some APIs. (optional)
+
+Any parameters could be not only strings, but any other variables with string Type.
+
+This is an example of using Translate():
 ::
 
    In [1]: from translate import Translator
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -13,3 +13,4 @@ tox
 twine
 vcrpy
 wheel
+setuptools
diff --git a/tests/fixtures/cassettes/test_tranlate_english_to_english.yaml b/tests/fixtures/cassettes/test_tranlate_english_to_english.yaml
@@ -0,0 +1,84 @@
+interactions:
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebit/535.19(KHTML, like
+        Gecko) Chrome/18.0.1025.168 Safari/535.19
+    method: GET
+    uri: http://api.mymemory.translated.net/get?q=why&langpair=autodetect%7Cen
+  response:
+    body:
+      string: "<html>\r\n<head><title>301 Moved Permanently</title></head>\r\n<body>\r\n<center><h1>301
+        Moved Permanently</h1></center>\r\n</body>\r\n</html>\r\n"
+    headers:
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '134'
+      Content-Type:
+      - text/html
+      Date:
+      - Fri, 31 Oct 2025 16:26:42 GMT
+      Location:
+      - https://api.mymemory.translated.net:443/get?q=why&langpair=autodetect%7Cen
+      Server:
+      - awselb/2.0
+    status:
+      code: 301
+      message: Moved Permanently
+- request:
+    body: null
+    headers:
+      Accept:
+      - '*/*'
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      User-Agent:
+      - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebit/535.19(KHTML, like
+        Gecko) Chrome/18.0.1025.168 Safari/535.19
+    method: GET
+    uri: https://api.mymemory.translated.net/get?q=why&langpair=autodetect%7Cen
+  response:
+    body:
+      string: '{"responseData":{"translatedText":"PLEASE SELECT TWO DISTINCT LANGUAGES"},"quotaFinished":null,"mtLangSupported":null,"responseDetails":"PLEASE
+        SELECT TWO DISTINCT LANGUAGES","responseStatus":"403","responderId":null,"exception_code":null,"matches":""}'
+    headers:
+      Access-Control-Allow-Origin:
+      - '*'
+      Cache-Control:
+      - no-cache, no-store, max-age=0, must-revalidate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '252'
+      Content-Type:
+      - application/json
+      Date:
+      - Fri, 31 Oct 2025 16:26:43 GMT
+      Expires:
+      - Fri, 01 Jan 1990 00:00:00 GMT
+      Pragma:
+      - no-cache
+      Server:
+      - Apache/2.4.41 (Ubuntu)
+      X-Backend-Content-Length:
+      - '10'
+      X-Embedded-Status:
+      - '200'
+      X-Frame-Options:
+      - SAMEORIGIN
+      X-XSS-Protection:
+      - '0'
+    status:
+      code: 200
+      message: OK
+version: 1
diff --git a/tests/test_provider.py b/tests/test_provider.py
@@ -5,7 +5,7 @@
 except Exception:
     import mock
 
-from translate.providers import MyMemoryProvider, MicrosoftProvider
+from translate.providers import MyMemoryProvider, MicrosoftProvider, YandexProvider
 
 
 def test_provider_mymemory_languages_attribute():
@@ -41,3 +41,21 @@ def raise_for_status(self):
     provider = MicrosoftProvider(to_lang='en', headers={}, secret_access_key='secret')
     provider._make_request('test')
     assert mock_requests_post.called
+
+@mock.patch('requests.Session.post')
+def test_provider_yandex_make_request(mock_requests_post):
+    class MockResponse:
+        text = '"dummyjson"'
+        def raise_for_status(self):
+            return False
+
+    mock_requests_post.return_value = MockResponse()
+    provider = YandexProvider(to_lang='en', secret_access_key='secret', folder_id='some_id')
+    provider.get_translation('test')
+    assert mock_requests_post.called
+
+    args, kwargs = mock_requests_post.call_args
+    assert 'Authorization' in kwargs['headers']
+    assert kwargs['json']['folderId'] == 'some_id'
+    assert kwargs['json']['targetLanguageCode'] == 'en'
+    assert kwargs['json']['texts'] == 'test'
diff --git a/translate/main.py b/translate/main.py
@@ -9,8 +9,9 @@
 import locale
 import sys
 
-from .translate import Translator
-from .version import __version__
+sys.path.append(os.path.dirname(os.path.dirname(__file__)))
+from translate import Translator
+from translate.version import __version__
 from .constants import CONFIG_FILE_PATH, DEFAULT_PROVIDER, TRANSLATION_FROM_DEFAULT
 
 
@@ -149,7 +150,7 @@ def config_file(ctx, from_lang, to_lang, provider, secret_access_key):
 @click.argument('text', nargs=-1, type=click.STRING, required=True)
 def main(from_lang, to_lang, provider, secret_access_key, output_only, pro, text, region):
     """
-    Python command line tool to make on line translations
+    Python command line tool to make online translations
 
     \b
     Example:
@@ -170,6 +171,7 @@ def main(from_lang, to_lang, provider, secret_access_key, output_only, pro, text
         kwargs['secret_access_key'] = secret_access_key
         kwargs['pro'] = pro
         kwargs['region'] = region
+        kwargs['folder_id'] = folder_id
 
     translator = Translator(**kwargs)
     translation = translator.translate(text)
diff --git a/translate/providers/__init__.py b/translate/providers/__init__.py
@@ -5,5 +5,6 @@
 from .microsoft import MicrosoftProvider  # noqa
 from .deepl import DeeplProvider  # noqa
 from .libre import LibreProvider
+from .yandex import YandexProvider
 
-__all__ = ['MyMemoryProvider', 'MicrosoftProvider', 'DeeplProvider', 'LibreProvider']
+__all__ = ['MyMemoryProvider', 'MicrosoftProvider', 'DeeplProvider', 'LibreProvider', 'YandexProvider']
diff --git a/translate/providers/base.py b/translate/providers/base.py
@@ -2,6 +2,7 @@
 # encoding: utf-8
 
 from abc import ABCMeta, abstractmethod
+import requests
 
 
 class BaseProvider:
@@ -10,14 +11,15 @@ class BaseProvider:
     name = ''
     base_url = ''
 
-    def __init__(self, to_lang, from_lang='en', secret_access_key=None, region=None, **kwargs):
+    def __init__(self, to_lang, from_lang='en', secret_access_key=None, region=None, folder_id=None, **kwargs):
         self.headers = {'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebit/535.19'
                                       '(KHTML, like Gecko) Chrome/18.0.1025.168 Safari/535.19'}
         self.from_lang = from_lang
         self.to_lang = to_lang
         self.secret_access_key = secret_access_key
         self.region = region
         self.kwargs = kwargs
+        self.session = requests.Session()
 
     @abstractmethod
     def get_translation(self, params):
diff --git a/translate/providers/yandex.py b/translate/providers/yandex.py
@@ -0,0 +1,59 @@
+import requests
+
+from .base import BaseProvider
+from ..constants import TRANSLATION_FROM_DEFAULT
+from ..exceptions import TranslationError
+
+class YandexProvider(BaseProvider):
+    '''
+    @YandexProvider: This is a integration with Yandex Translate API.
+    Website: https://translate.yandex.com/
+    Documentation: https://yandex.cloud/en/docs/translate
+    '''
+    name = "Yandex"
+    base_url = "https://translate.api.cloud.yandex.net/translate/v2/translate"
+    session = None
+
+    def __init__(self, to_lang, from_lang=None, secret_access_key=None, base_url=None, folder_id=None, is_iam=False, **kwargs):
+        super().__init__(to_lang)
+        self.from_lang = from_lang
+        self.base_url = base_url
+        self.api = secret_access_key
+        self.folder_id = folder_id # Folders used by Yandex API
+        self.is_iam = is_iam # Yandex can authorise us using API or IAM tokens
+
+    def get_translation(self, text):
+        is_autodetect = False
+        if self.from_lang in ('autodetect', None):
+            self.from_lang = None 
+            is_autodetect = True # We can send Yandex nothing if we want it to detect language automatically
+
+        try:
+            body = {
+                "targetLanguageCode": self.to_lang,
+                "texts": text,
+                "folderId": self.folder_id,
+            }
+
+            if not is_autodetect:
+                body["sourceLanguageCode"] = self.from_lang # Inserting source language if we're not going to autodetect it
+
+            headers = {
+                "Content-Type": "application/json",
+            }
+
+            if self.is_iam:
+                headers["Authorization"] = "Bearer {0}".format(self.api) # Passing to Yandex our IAM-token
+            else:
+                headers["Authorization"] = "Api-Key {0}".format(self.api) # Passing to Yandex our API-token
+
+            response = self.session.post(
+                self.base_url,
+                json=body,
+                headers=headers,
+            )
+
+            return response.text
+        except Exception as e:
+            raise TranslationError(e)        
+
diff --git a/translate/translate.py b/translate/translate.py
@@ -3,7 +3,8 @@
 from textwrap import wrap
 
 from .exceptions import InvalidProviderError
-from .providers import MyMemoryProvider, MicrosoftProvider, DeeplProvider, LibreProvider
+from .providers import MyMemoryProvider, MicrosoftProvider, DeeplProvider, LibreProvider, YandexProvider
+from .constants import TRANSLATION_FROM_DEFAULT
 
 DEFAULT_PROVIDER = MyMemoryProvider
 TRANSLATION_API_MAX_LENGTH = 1000
@@ -13,11 +14,12 @@
     'microsoft': MicrosoftProvider,
     'deepl': DeeplProvider,
     'libre': LibreProvider,
+    'yandex': YandexProvider
 }
 
 
 class Translator:
-    def __init__(self, to_lang, from_lang='en', provider=None, secret_access_key=None, region=None, **kwargs):
+    def __init__(self, to_lang, from_lang=TRANSLATION_FROM_DEFAULT, provider=None, secret_access_key=None, region=None, folder_id=None, **kwargs):
         self.available_providers = list(PROVIDERS_CLASS.keys())
         self.from_lang = from_lang
         self.to_lang = to_lang
@@ -34,6 +36,7 @@ def __init__(self, to_lang, from_lang='en', provider=None, secret_access_key=Non
             to_lang=to_lang,
             secret_access_key=secret_access_key,
             region=region,
+            folder_id=folder_id,
             **kwargs
         )
 

-Original file line number
+Diff line change
 twine
 vcrpy
 wheel
 +setuptools