Merge pull request #47 from ch3p4ll3/v2-add-localization

V2 add localization

.gitignore

@@ -52,6 +52,7 @@ coverage.xml
 .pytest_cache/
 cover/
 
+.vscode/
 # Translations
 *.mo
 *.pot

README.md

@@ -1,4 +1,9 @@
+![GitHub License](https://img.shields.io/github/license/ch3p4ll3/QBittorrentBot)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/259099080ca24e029a910e3249d32041)](https://app.codacy.com/gh/ch3p4ll3/QBittorrentBot?utm_source=github.com&utm_medium=referral&utm_content=ch3p4ll3/QBittorrentBot&utm_campaign=Badge_Grade)
+![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/ch3p4ll3/QBittorrentBot/docker-image.yml)
+![Docker Pulls](https://img.shields.io/docker/pulls/ch3p4ll3/qbittorrent-bot)
+
+
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
@@ -13,6 +18,21 @@ magnet:?xt=...
 ```
 You can also pause, resume, delete and add/remove and modify categories.
 
+# Table Of Contents
+- [QBittorrentBot](#qbittorrentbot)
+- [Table Of Contents](#table-of-contents)
+  - [Warning!](#warning)
+  - [Configuration](#configuration)
+    - [Retrieve Telegram API ID and API HASH](#retrieve-telegram-api-id-and-api-hash)
+    - [JSON Configuration](#json-configuration)
+  - [Running](#running)
+    - [Build docker](#build-docker)
+    - [Running without docker](#running-without-docker)
+  - [Contributing Translations on Transifex](#contributing-translations-on-transifex)
+  - [How to enable the qBittorrent Web UI](#how-to-enable-the-qbittorrent-web-ui)
+  - [Contributors ✨](#contributors-)
+
+
 ## Warning!
 Since version V2, the mapping of the configuration file has been changed. Make sure you have modified it correctly before starting the bot
 
@@ -68,6 +88,25 @@ Pull and run the image with: `docker run -d -v /home/user/docker/QBittorrentBot:
 - Create a config.json file
 - Start the bot with `python3 main.py`
 
+## Contributing Translations on Transifex
+QBittorrentBot is an open-source project that relies on the contributions of its community members to provide translations for its users. If you are multilingual and would like to help us make QBittorrentBot more accessible to a wider audience, you can contribute by adding new translations or improving existing ones using Transifex:
+
+- Visit the [QBittorrentBot Transifex Project](https://app.transifex.com/ch3p4ll3/qbittorrentbot/).
+
+- If you don't have a Transifex account, sign up for one. If you already have an account, log in.
+
+- Navigate to the "Languages" tab to view the available languages. Choose the language you want to contribute to.
+
+- Locate the specific string you wish to translate. Please note that the text between "${" and "}" should not be edited, as they are placeholders for dynamic content.
+
+- Click on the string you want to translate, enter your translation in the provided field, and save your changes.
+
+- If your language is not listed, you can request its addition.
+
+- Once you have completed your translations, submit them for review. The project maintainers will review and approve your contributions.
+
+Thank you for helping improve QBittorrentBot with your valuable translations!
+
 ## How to enable the qBittorrent Web UI
 For the bot to work, it requires qbittorrent to have the web interface active. 
 You can activate it by going on the menu bar, go to **Tools > Options** qBittorrent WEB UI

config.json.template

@@ -1,20 +1,28 @@
 {
     "client": {
         "type": "qbittorrent",
-        "host": "http://192.168.178.102",
+        "host": "http://192.168.178.102:8080",
         "user": "admin",
         "password": "admin"
     },
     "telegram": {
         "bot_token": "1111111:AAAAAAAA-BBBBBBBBB",
         "api_id": 1111,
-        "api_hash": "aaaaaaaa"
+        "api_hash": "aaaaaaaa",
+        "proxy": {
+            "scheme": "http",
+            "hostname": "myproxy.local",
+            "port": 8080,
+            "username": "admin",
+            "password": "admin"
+        }
     },
 
     "users": [
         {
             "user_id": 123456,
             "notify": false,
+            "locale": "en",
             "role": "administrator"
         }
     ]

docker-compose.yml.example

@@ -0,0 +1,8 @@
+version: '3.9'
+services:
+    qbittorrent-bot:
+        image: 'ch3p4ll3/qbittorrent-bot:latest'
+        container_name: qbittorrent-bot
+        restart: unless-stopped
+        volumes:
+            - '/home/user/docker/QBittorrentBot:/app/config:rw'

docs/advanced/add_new_client_manager.md

@@ -37,7 +37,7 @@ class ClientTypeEnum(str, Enum):
 - Return to the `src/client_manager` folder and edit the `client_repo.py` file by adding to the dictionary named `repositories` an entry associating the newly created enum with the new manager. Example:
 ```python
 from ..configs.enums import ClientTypeEnum
-from .qbittorrent_manager import QbittorrentManager, ClientManager
+from .qbittorrent_manager import QbittorrentManager, ClientManager, UtorrentManager
 
 
 class ClientRepo:

docs/advanced/telegram_proxy.md

@@ -0,0 +1,32 @@
+# Configure proxy for Telegram
+
+QBittorrent Bot can be configured to use a Telegram proxy to connect to the Telegram API. This can be useful if you are behind a firewall that blocks direct connections to Telegram.
+
+To configure QBittorrent Bot to use a Telegram proxy, you will need to add a **proxy section** to the `config.json` file in the **telegram section**. The telegram section should have the following format:
+
+```json5
+"telegram": {
+    "bot_token": "1111111:AAAAAAAA-BBBBBBBBB",
+    "api_id": 1111,
+    "api_hash": "aaaaaaaa",
+    "proxy": {
+        "scheme": "http", // http, sock4 or sock5
+        "hostname": "myproxy.local",
+        "port": 8080,
+        "username": "admin",
+        "password": "admin"
+  }
+}
+```
+
+Where:
+
+- `scheme` is the protocol to use for the proxy connection. This can be `http`, `sock4` or `sock5`
+- `hostname` is the hostname or IP address of the proxy server.
+- `port` is the port number of the proxy server.
+- `username` (optional) is the username for the proxy server.
+- `password` (optional) is the password for the proxy server.
+
+!!!
+Once you have added the proxy section to the config.json file, you will need to restart QBittorrent Bot for the changes to take effect.
+!!!

docs/contributing.md

@@ -0,0 +1,30 @@
+---
+order: -10
+---
+# Contributing
+QBittorrentBot is an open-source Telegram bot that enables seamless management of qBittorrent downloads directly from Telegram. 
+
+By contributing to QBittorrentBot, you can help improve this valuable tool for qBittorrent users. Your contributions can range from fixing bugs and enhancing existing features to adding new functionalities that enhance the bot's capabilities.
+
+## Adding translations
+If you are multilingual and would like to help us make QBittorrentBot more accessible to a wider audience, you can contribute by adding new translations or improving existing ones using Transifex:
+
+- Visit the [QBittorrentBot Transifex Project](https://app.transifex.com/ch3p4ll3/qbittorrentbot/).
+
+- If you don't have a Transifex account, sign up for one. If you already have an account, log in.
+
+- Navigate to the "Languages" tab to view the available languages. Choose the language you want to contribute to.
+
+- Locate the specific string you wish to translate. Please note that the text between "${" and "}" should not be edited, as they are placeholders for dynamic content.
+
+- Click on the string you want to translate, enter your translation in the provided field, and save your changes.
+
+- If your language is not listed, you can request its addition.
+
+- Once you have completed your translations, submit them for review. The project maintainers will review and approve your contributions.
+
+Thank you for helping improve QBittorrentBot with your valuable translations!
+
+
+[!ref](/advanced/add_new_client_manager.md)
+[!ref](/advanced/add_entries_configuration.md)

docs/faq.md

@@ -61,4 +61,6 @@ Please follow this guide
 
 ### How do I contribute to the development of QBittorrentBot?
 
-QBittorrentBot is an open-source project. You can contribute to the development by reporting bugs, suggesting improvements, or submitting pull requests. The project's code is hosted on [GitHub](https://github.com/ch3p4ll3/QBittorrentBot).
+QBittorrentBot is an open-source project. You can contribute to the development by reporting bugs, suggesting improvements, or submitting pull requests. The project's code is hosted on [GitHub](https://github.com/ch3p4ll3/QBittorrentBot).
+
+[!ref](/contributing.md)

docs/getting_started/configuration_file.md

@@ -32,15 +32,15 @@ Here's a brief overview of the configuration file and its key sections:
 
 - **Clients Section**: Establishes the connection details for the qBittorrent server, including the hostname, port number, username, and password. This enables the bot to interact with the qBittorrent server and manage torrents.
 
-- **Telegram Section**: Contains the bot token, API ID, and API hash, which are essential for authenticating the bot with the Telegram API. These credentials allow the bot to communicate with the Telegram server and receive user commands. Click [here](https://docs.pyrogram.org/intro/quickstart) to find out how to retrive your API ID and API Hash
+- **Telegram Section**: Contains the bot token, API ID, and API hash, which are essential for authenticating the bot with the Telegram API. These credentials allow the bot to communicate with the Telegram server and receive user commands. Click [here](https://core.telegram.org/api/obtaining_api_id) to find out how to retrive your API ID and API Hash
 
 - **Users Section**: Lists the authorized users of the QBittorrentBot, along with their Telegram user IDs, notification preferences, and user roles. This section defines the users who can interact with the bot, receive notifications, and manage torrents.
 
 ## Client
 
 This section defines the configuration for the qBittorrent client that the bot will be interacting with.
 
-Name     | Type                              | Value
+Name     | Type                              | Remarks
 ---      |-----------------------------------| ---
 type     | [ClientTypeEnum](#clienttypeenum) | The type of client.
 host     | [HttpUrl](#httpurl)               | The IP address of the qBittorrent server.
@@ -51,43 +51,69 @@ password | str                               | The password for the qBittorrent
 
 This section defines the configuration for the Telegram bot that the QBittorrentBot will be communicating with.
 
-Name      | Type | Value
----       | ---  | ---
-bot_token | str  | The bot token for the QBittorrentBot. This is a unique identifier that is used to authenticate the bot with the Telegram API.
-api_id    | int  | The API ID for the QBittorrentBot. This is a unique identifier that is used to identify the bot to the Telegram API.
-api_hash  |str   | The API hash for the QBittorrentBot. This is a string of characters that is used to verify the authenticity of the bot's requests to the Telegram API.
+Name      | Type                                              | Remarks
+---       | ---                                               | ---
+bot_token | str                                               | The bot token for the QBittorrentBot. This is a unique identifier that is used to authenticate the bot with the Telegram API.
+api_id    | int                                               | The API ID for the QBittorrentBot. This is a unique identifier that is used to identify the bot to the Telegram API.
+api_hash  | str                                               | The API hash for the QBittorrentBot. This is a string of characters that is used to verify the authenticity of the bot's requests to the Telegram API.
+proxy     | [TelegramProxySettings](#telegram-proxy-settings) | Optional, the settings for using a proxy to contact telegram servers
 
 
 ## Users
 
 This section defines the list of users who are authorized to use the QBittorrentBot. Each user is defined by their Telegram user ID, whether or not they should be notified about completed torrents, and their role.
 
-Name     | Type                            | Value
----      | ---                             |---
-user_id  | int                             |The Telegram user ID of the user. This is a unique identifier that is used to identify the user to the Telegram API.
-notify   | bool                            |Whether or not the user should be notified about new torrents.
-role     | [UserRolesEnum](#userrolesenum) |The role of the user.
-
+Name     | Type                            | Remarks
+---      | ---                             | ---
+user_id  | int                             | The Telegram user ID of the user. This is a unique identifier that is used to identify the user to the Telegram API.
+notify   | bool                            | Whether or not the user should be notified about new torrents.
+role     | [UserRolesEnum](#userrolesenum) | The role of the user. Default: `administrator`
+locale   | str                             | Language used by the user, [list of supported languages](#languages). Default: `en`
 
 ## Enums
 
 ### ClientTypeEnum
 
 Name        | Type   | Value(to be used in json)
 ---         | ---    |---
-QBittorrent | str    | qbittorrent
+QBittorrent | str    | `qbittorrent`
 
 ### UserRolesEnum
 Name         | Type   | Value(to be used in json) | Remarks
 ---          | ---    |---                        | 
-Reader       | str    | reader                    | Can perform only reading operations(view torrents)
-Manager      | str    | manager                   | Can perform only managing operations(view torrents + can download files + can add/edit categories + set torrent priority + can stop/start downloads)
-Administrator| str    | administrator             | Can perform all operations (Manager + remove torrent + remove category + edit configs)
+Reader       | str    | `reader`                    | Can perform only reading operations(view torrents)
+Manager      | str    | `manager`                   | Can perform only managing operations(view torrents + can download files + can add/edit categories + set torrent priority + can stop/start downloads)
+Administrator| str    | `administrator`             | Can perform all operations (Manager + remove torrent + remove category + edit configs)
+
+### Telegram Proxy Scheme
+Name        | Type   | Value(to be used in json)
+---         | ---    |---
+Sock4       | str    | `socks4`
+Sock5       |str     | `socks5`
+Http        |str     | `http`
 
 ## Other types
 
 ### HttpUrl
 A type that will accept any http or https URL.
 - TLD required
 - Host required
-- Max length 2083
+- Max length 2083
+
+### Languages
+Name             | Type   | Value(to be used in json)
+---              | ---    |---
+English          | str    | `en`
+Italian          | str    | `it`
+Ukrainian        | str    | `uk_UA`
+Russian(Ukraine) | str    | `ru_UA`
+
+### Telegram Proxy Settings
+QBittorrentBot supports proxies with and without authentication. This feature allows QBittorrentBot to exchange data with Telegram through an intermediate SOCKS 4/5 or HTTP proxy server.
+
+Name       | Type                                          | Remarks
+---        | ---                                           | ---
+scheme     | [TelegramProxyScheme](#telegram-proxy-scheme) | The scheme to be used to connect to the proxy
+hostname   | str                                           | The hostname of the proxy
+username   | str                                           | Optional, the proxy user
+password   | str                                           | Optional, the proxy password

docs/getting_started/index.md

@@ -1,29 +1,10 @@
 # Getting Started
+QBittorrentBot is a Telegram bot that allows you to control your qBittorrent client from within the Telegram messaging app. This makes it easy to add new torrents, manage your existing downloads, and get status updates without having to switch between applications.
 
-In order to start using the bot, you must first create a folder where the bot will fish for settings and where it will save logs
+## Prerequisites
 
-For example: let's create a folder called `QBittorrentBot` in the home of the user `user`. The path to the folder will then be `/home/user/docker/QBittorrentBot`.
-
-Before starting the bot you need to place the configuration file in this folder. You can rename the `config.json.template` file to `config.json` and change the parameters as desired. Go [here](configuration_file.md) to read more about the configuration file.
-
-Once that is done you can start the bot using docker, you can use either docker or docker compose.
-
-+++ Docker
-Open your terminal and execute the following command to start the bot container:
-
-`docker run -d -v /home/user/docker/QBittorrentBot:/app/config:rw --name qbittorrent-bot ch3p4ll3/qbittorrent-bot:latest`
-+++ Docker compose
-Create a file named `docker-compose.yml` inside a directory with the following content:
-```
-version: '3.9'
-services:
-    qbittorrent-bot:
-        image: 'ch3p4ll3/qbittorrent-bot:latest'
-        container_name: qbittorrent-bot
-        restart: unless-stopped
-        volumes:
-            - '/home/user/docker/QBittorrentBot:/app/config:rw'
-```
-
-Run the following command to start the bot using Docker Compose:
-`docker compose up -d`
+- A Telegram account
+  - A bot token obtained from [botfather](https://core.telegram.org/bots#how-do-i-create-a-bot)
+  - [Telegram API ID](https://core.telegram.org/api/obtaining_api_id)
+- A running qBittorrent instance with WebUI enabled
+- Access to your qBittorrent server's IP address and port number