{"id":25733815,"url":"https://github.com/brooks-code/special-octo-telegram","last_synced_at":"2025-02-26T04:30:39.322Z","repository":{"id":278378331,"uuid":"908743545","full_name":"brooks-code/special-octo-telegram","owner":"brooks-code","description":"Automate online translations using Selenium.","archived":false,"fork":false,"pushed_at":"2025-02-19T12:27:41.000Z","size":109,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-19T13:29:49.305Z","etag":null,"topics":["botautomation","deepl","geckodriver","selenium","translation","webdriver"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brooks-code.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":"2024-12-26T21:11:56.000Z","updated_at":"2025-02-19T12:30:46.000Z","dependencies_parsed_at":"2025-02-19T13:29:53.631Z","dependency_job_id":"c46503d1-9492-40be-a649-cb48319f81d4","html_url":"https://github.com/brooks-code/special-octo-telegram","commit_stats":null,"previous_names":["brooks-code/special-octo-telegram"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooks-code%2Fspecial-octo-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooks-code%2Fspecial-octo-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooks-code%2Fspecial-octo-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooks-code%2Fspecial-octo-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brooks-code","download_url":"https://codeload.github.com/brooks-code/special-octo-telegram/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240794373,"owners_count":19858713,"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":["botautomation","deepl","geckodriver","selenium","translation","webdriver"],"created_at":"2025-02-26T04:30:38.639Z","updated_at":"2025-02-26T04:30:39.195Z","avatar_url":"https://github.com/brooks-code.png","language":"Python","readme":"# DeepL Translator Script\n\n**Translate effortlessly: automate text translations with the DeepL service using Selenium.**\n\n![Banner Image](/img/banner-img.jpg \"A banner image depicting a cat playing on the tower of Babel.\")\n*Pastiche by FatCatArt inspired by Pieter Bruegel the elder's tower of Babel.*\n\n### Genesis\n\n\u003eThe idea occured while translating news articles from multiple languages. This was a real pain point on a recent personal project: the restrictive character limit made it difficult to get an overview of the full article. This script provides a way to get a better translation experience at once without having to tediously copy and paste the translated text chunks. A real time-saver :)\n\nAs a student I took this side project as an opportunity to discover automation using Selenium and implement some coding best practices learned at school.\nThe project not only solved an immediate problem, but also deepened my practical software development skills. If you are eager to learn more, dive into the code! The **tutorial** articles are available here:\n\n* [Part I: setup](https://dev.to/atomictangerline/basic-selenium-the-easy-peasy-introduction-chapter-1-of-3-4fe3)\n* [Part II: overview](https://dev.to/atomictangerline/basic-selenium-the-easy-peasy-introduction-chapter-2-of-3-1oad)\n* [Part III: deep dive](https://dev.to/atomictangerline/basic-selenium-the-easy-peasy-introduction-chapter-3-of-3-3bb7)\n\n**NB:** This script uses the [DeepL translation service](https://www.deepl.com/translator), which has usage limits and requires a subscription for heavy usage.\n\n\u003e [!NOTE]\n\u003e Be aware that in the constantly shifting landscape of website updates, this script may become disrupted unexpectedly. It was last verified to be functioning as of *February 2025*.\n\n## Table of Content\n\n\u003cdetails\u003e\n\u003csummary\u003e Contents - click to expand\u003c/summary\u003e\n\n- [DeepL Translator Script](#deepl-translator-script)\n    - [Genesis](#genesis)\n  - [Table of Content](#table-of-content)\n  - [Requirements](#requirements)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [Configuration](#configuration)\n  - [Limitations](#limitations)\n  - [Troubleshooting](#troubleshooting)\n  - [Further learning](#further-learning)\n  - [Contributing](#contributing)\n  - [Legal](#legal)\n    - [License](#license)\n    - [Acknowledgments](#acknowledgments)\n    - [Disclaimer](#disclaimer)\n\n\u003c/details\u003e\n\n## Requirements\n\n* Python 3.x\n* Selenium\n* GeckoDriver [(available here)](https://github.com/mozilla/geckodriver/releases)\n\n## Installation\n\n1. Clone or download this repository.\n2. If you don't have it yet, install Firefox on your system/environment. This is the command for debian-based distros like Ubuntu:\n\n    ```bash\n    sudo apt update \u0026\u0026 sudo apt install firefox\n3. Install the required packages using pip:\n\n   ```bash\n    pip install -r requirements.txt\n4. Download the GeckoDriver executable from the official Mozilla [repository](https://github.com/mozilla/geckodriver/), extract it to /opt (common practice) or any directory you prefer (update the directories accordingly), set the permissions and create symbolic links to make the webdriver available in the system's PATH.\n\n   ```bash\n    wget https://github.com/mozilla/geckodriver/releases/download/v0.35.0/geckodriver-v0.35.0-linux64.tar.gz -O /tmp/geckodriver.tar.gz \\\n    \u0026\u0026 sudo tar -C /opt -xzf /tmp/geckodriver.tar.gz \\\n    \u0026\u0026 sudo chmod 755 /opt/geckodriver \\\n    \u0026\u0026 sudo ln -fs /opt/geckodriver /usr/bin/geckodriver \\\n    \u0026\u0026 sudo ln -fs /opt/geckodriver /usr/local/bin/geckodriver\n\n\u003e [!NOTE]\n\u003e**WSL2 users:** In order to launch Firefox, it is possible set up Windows to run Linux GUI apps. Depending on your OS version, follow this [tutorial](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps) or this [one](https://aalonso.dev/blog/2021/how-to-use-gui-apps-in-wsl2-forwarding-x-server-cdj).\n\n## Usage\n\n1. Update the `INPUT_FILE` and `OUTPUT_FILE` parameters in the script to point to your input and output files. The script will process any file that contains *text*:\n\n    * Plain text files (.txt)\n    * Markdown files (.md)\n    * HTML files (.html, .htm)\n    * XML files (.xml)\n    * JSON files (.json)\n    * CSV files (.csv)  \n    * *or any other type of file that contains text data.*\n  \n\u003e [!IMPORTANT]\n\u003e The script *requires* an **input** file. If no **output** file exists at the specified location, a new one will be created; otherwise, the existing output file will be overwritten each time the script is run.\n\n2. Run the script in the terminal:\n\n    ```bash\n    python translator.py\n3. The script will translate the text found in the input file and write the translation to the output file (the output file will be created if it does not exist and overwritten otherwise).\n\n## Configuration\n\nThe script uses the following configuration variables:\n\n* `FIREFOX_PATH`: The path to the Firefox executable. Command to check its location (Linux/macOS):\n\n    ```bash\n    which firefox\n* `GECKODRIVER_PATH`: The path to the GeckoDriver executable. It should be the one provided during the installation. You can check it with this command:\n\n    ```bash\n    which geckodriver\n* `HEADLESS`: A boolean variable that determines whether to run the browser in headless mode.\n\n* `SOURCE_LANG`: The source language of the text to translate (currently set to English (US)). For other available languages, see the list below.\n* `OUTPUT_LANG`: The target language of the text to translate (currently set to French). For other available languages, see the list below.\n* `CHAR_LIMIT`: Maximum character limit for each chunk of text to be translated (currently set to 1500 characters).\n* `TIMEOUT`: The timeout in seconds for Selenium to wait for elements to load.\n* `SLEEP_TIME`: The time in seconds to wait between translating each chunk of text.\n\n\u003cdetails\u003e\n\u003csummary\u003e List of supported languages (Nov. 2024):\u003c/summary\u003e\n\n| Language      | Language code|\n| ------------- | ------------- |\n| Arabic  | ar  |\n| Bulgarian  | bg  |\n| Chinese (simple) | zh-hans  |\n| Chinese  (traditional)| zh-hant  |\n| Czech  | cs  |\n| Danish  | da  |\n| Dutch  | nl  |\n| English  | en  |\n| English (US) | en-us  |\n| Estonian  | et  |\n| Finnish  | fi  |\n| French  | fr  |\n| German  | de  |\n| Greek  | el  |\n| Hungarian  | hu  |\n| Indonesian  | id  |\n| Italian  | it  |\n| Japanese  | ja  |\n| Korean  | ko  |\n| Latvian  | lv  |\n| Lithuanian  | lt  |\n| Norwegian (Bokmål)  | nb  |\n| Polish  | pl  |\n| Portuguese  | pt-pt  |\n| Portuguese (Brazil) | pt-br  |\n| Romanian  | ro  |\n| Russian  | ru  |\n| Slovak  | sk  |\n| Slovenian  | sl  |\n| Spanish  | es  |\n| Swedish  | sv  |\n| Turkish  | tr  |\n| Ukrainian  | uk  |\n\n\u003c/details\u003e\n\n## Limitations\n\n\u003e [!WARNING]\n\u003e It's important to note that if you don't manually rename the output file variable after each run, the script will overwrite the previous file, causing you to lose its content.\n\nThe script was developed with Firefox in mind. If you are a Chrome user, you will have to modify the code to initiate an instance of [Chromedriver](https://developer.chrome.com/docs/chromedriver/downloads) instead of Geckodriver.\n\nThe script is intended as an educational side project, and is not meant for extensive use. If you use the script too frequently, you may quickly hit some usage limits potentially resulting in your IP address being blacklisted.\n\n\u003e [!TIP]\n\u003e As the script currently only supports processing a single input file at a time. The recommended approach is to gather all your source texts into a single file. You will then get them translated into one output file.\n\n## Troubleshooting\n\nIf the script fails to launch the browser, check that the `FIREFOX_PATH` and `GECKODRIVER_PATH` variables are set correctly.\n\nIf the script fails to translate the text, check that the `SOURCE_LANG` and `OUTPUT_LANG` variables are set correctly.\n\nIf the script fails to write the translated text to the output file, check that the `OUTPUT_FILE` variable is set correctly.\n\nIf the script translates the text into German instead of the specified `OUTPUT_LANG`. It's possible that the webdriver connects to the website but has not managed to switch languages (German is DeepL's default output language). Try adjusting the `SLEEP_TIME` to a higher value.\n\n## Further learning\n\n* A tutorial that inspired this project: [YouTube link](https://www.youtube.com/watch?v=aSeqMYNhEHo)\n* The tutorial about this project: [Available here](https://dev.to/atomictangerline/series/30533)\n\n## Contributing\n\nContributions are **welcome!** I appreciate your support: each contribution and feedback helps me grow and improve.\n\nThis project is intended as a practice on a real world use case, feel free to play with it. I'm open to any suggestion that will improve the code quality and deepen my software programming skills. If you'd like to contribute to this project, please fork the repository and submit a pull request with your changes.\n\n## Legal\n\n### License\n\nThe source code is provided under a [Creative Commons CC0 license](https://creativecommons.org/publicdomain/zero/1.0/). See the [LICENSE](/LICENSE) file for details.\n\n### Acknowledgments\n\nThis project uses the following libraries and services:\n\n* [GeckoDriver](https://github.com/mozilla/geckodriver/releases): a WebDriver implementation for [Mozilla Firefox](https://mozilla.org/firefox)\n* [Selenium's WebDriver](https://www.selenium.dev/documentation/webdriver/): a browser automation framework\n* [DeepL](https://www.deepl.com/translator): an online (deep learning based) translation service\n\n### Disclaimer\n\nThis project is not affiliated with DeepL or Mozilla. The use of the DeepL or any other translation service is subject to their terms and conditions.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrooks-code%2Fspecial-octo-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrooks-code%2Fspecial-octo-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrooks-code%2Fspecial-octo-telegram/lists"}