Metadata-Version: 2.4
Name: collective.translators
Version: 1.0.0a1
Summary: Pluggable external translation utilities for Plone
Home-page: https://github.com/collective/collective.translators
Author: Mauro Amico
Author-email: mauro.amico@gmail.com
License: GPL version 2
Project-URL: PyPI, https://pypi.org/project/collective.translators
Project-URL: Source, https://github.com/collective/collective.translators
Project-URL: Tracker, https://github.com/collective/collective.translators/issues
Keywords: Python Plone CMS
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: Addon
Classifier: Framework :: Plone :: 6.0
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.GPL
License-File: LICENSE.md
Requires-Dist: plone.api
Requires-Dist: plone.app.multilingual
Requires-Dist: plone.app.registry
Requires-Dist: plone.base
Requires-Dist: plone.restapi
Requires-Dist: Products.CMFCore
Requires-Dist: Products.CMFPlone
Requires-Dist: requests
Requires-Dist: Zope
Provides-Extra: test
Requires-Dist: plone.app.contenttypes; extra == "test"
Requires-Dist: plone.app.testing; extra == "test"
Requires-Dist: plone.restapi[test]; extra == "test"
Requires-Dist: plone.testing; extra == "test"
Provides-Extra: release
Requires-Dist: zest.releaser[recommended]; extra == "release"
Requires-Dist: zestreleaser.towncrier; extra == "release"
Requires-Dist: zest.pocompile; extra == "release"
Provides-Extra: aws
Requires-Dist: boto3; extra == "aws"
Provides-Extra: chatgpt
Requires-Dist: openai; extra == "chatgpt"
Provides-Extra: deepseek
Requires-Dist: openai; extra == "deepseek"
Provides-Extra: deepl
Requires-Dist: deepl; extra == "deepl"
Provides-Extra: ollama
Requires-Dist: ollama; extra == "ollama"
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist

# collective.translators

This package extends [plone.app.multilingual](https://github.com/plone/plone.app.multilingual) by providing pluggable external translation utilities for automatic content translation in Plone. It enables seamless integration with multiple translation providers, allowing site administrators to configure and use services such as DeepL, AWS Translate, LibreTranslate, DeepSeek, and Ollama for translating site content.

PR #468 (https://github.com/plone/plone.app.multilingual/pull/468) is a strict requirement for this addon.

## Translator Utilities

This package provides pluggable translation utilities for multiple providers. Each utility exposes a similar interface for translating content and checking available languages.

Each utility is registered as a factory and can be enabled/configured via the Plone control panel. They provide a consistent API for translation tasks, making it easy to switch between providers.

### 1. DeepL Translator (`DeeplTranslatorFactory`)

Integrates with the DeepL API (Free and Pro endpoints supported). Reads the API key from the Plone registry. Supports autodetection of source language and translation of text or HTML.

### 2. AWS Translate (`AWSTranslatorFactory`)

Uses Amazon AWS Translate. Reads credentials and region from the Plone registry. Handles translation and language autodetection fallback.

### 3. LibreTranslate (`LibreTranslateTranslatorFactory`)

Integrates with the open-source LibreTranslate server. The server URL and API key can be configured. Supports autodetection and both text and HTML formats.

### 4. DeepSeek Translator (`DeepSeekFactory`)

Integrates with DeepSeek, an LLM-based translation API. Reads the API key from the registry. Uses chat completions for translation.

### 5. Ollama Translator (`OllamaTranslatorFactory`)

Integrates with the Ollama local LLM server. Allows translation using models running on your own hardware. The Ollama server URL and model can be configured. Useful for private or offline translation tasks.

### 6. Google Translate (`GoogleTranslateCloudAPIFactory`)

Integrates with the Google Translate Cloud API.

### 7. ChatGPT (`ChatGPTFactory`)

Integrates with the OpenAI API. Reads credentials from the Plone registry.

---

## Installation and usage

Install this product as a dependency of your project: `collective.translators`

If you require AWS, Deepl, DeepSeek or Ollama support, install the product requiring the required extra:

- `collective.translators[deepl]`
- `collective.translators[deepl,aws]`

Google Translate and Libre Translate support is embedded because they just require HTTP requests to work.

## Adding a New Tool

You can contribute a new translation tool (utility) by either:

- Proposing it via a pull request (PR) within this package, following the structure below, or
- Creating a separate Plone add-on package that provides an external translation utility implementing the same interface and registration pattern.

To add a new translation tool (utility) follow these steps:

1. **Implement and Register Your Utility**

   - Your utility class must implement the `IExternalTranslationService` interface from `plone.app.multilingual.interfaces`.
   - It should provide at least these methods:
     - `is_available()`: Returns True if the service is enabled and ready.
     - `available_languages()`: Returns a list of supported language codes or pairs.
     - `translate_content(content, source_language, target_language, ...)`: Performs the translation and returns the translated text.
   - Register your utility in its `configure.zcml` using:
     ```xml
     <utility
         provides="plone.app.multilingual.interfaces.IExternalTranslationService"
         name="your_tool_name"
         component=".utility.YourTranslator"
     />
     ```
   - Follow the structure and API of the existing utilities (see `utility.py` and `configure.zcml` in other tool folders) to ensure compatibility.

2. **Register Your Tool**

   - In `src/collective/translators/configure.zcml`, add:
     ```xml
     <include package=".mytool" />
     ```

3. **(Optional) Create a Control Panel**

   - If you want user-configurable settings for your tool, add:
     - A registry interface in `interfaces.py`.
     - Registry configuration defaults in `profiles/default/registry/youtool.xml`
     - Add ontrolpanel registration in `profiles/default/controlpanel.xml`
     - A control panel form and adapter in `controlpanel/controlpanel.py`, and register it in the relevant ZCML and `controlpanel/configure.zcml`.
   - See the existing tools for concrete examples of each file and configuration.

4. **Test Your Tool**
   - Restart your site, access your tool's control panel, add your API key or settings, and test translation.

Refer to the code of existing tools (e.g. DeepL, AWS, LibreTranslate, DeepSeek, Ollama, Google) for examples of each file and configuration.

## Contribute

- [Issue Tracker](https://github.com/collective/collective.translators/issues)
- [Source Code](https://github.com/collective/collective.translators/)

## License

The project is licensed under GPLv2.
