Translation
===========

ForkBit includes a built-in translation service (DeepL or Apple Translate).
Plugins access it via :meth:`~forkbit_sdk.BasePlugin.translate` — translations
run asynchronously in a background thread.

Translate release notes
-----------------------

.. code-block:: python

   def _translate_notes(self, target_lang: str) -> None:
       text = self.editor.toPlainText()
       if not text.strip():
           self.notify("Nothing to translate.", level="warning")
           return

       self.translate(
           text=text,
           source_lang="en",
           target_lang=target_lang,
           on_done=self._on_translation_done,
           on_error=self._on_translation_error,
       )
       self.notify(f"Translating to {target_lang}...")

   def _on_translation_done(self, translated_text: str) -> None:
       self.editor.setPlainText(translated_text)
       self.notify("Translation complete.", level="success")

   def _on_translation_error(self, error: str) -> None:
       self.notify(f"Translation failed: {error}", level="error")

How it works
------------

1. :meth:`~forkbit_sdk.BasePlugin.translate` queues the request and returns
   a request ID immediately
2. The translation runs in a background thread
3. When finished, your ``on_done`` callback receives the translated text
4. On failure, ``on_error`` receives an error message

Both callbacks run on the main thread — safe to update UI directly.

Language codes
--------------

Use standard language codes:

- ``"en"`` — English
- ``"de"`` — German
- ``"fr"`` — French
- ``"es"`` — Spanish
- ``"ja"`` — Japanese
- ``"zh"`` — Chinese

The full list depends on the configured translation provider (DeepL or
Apple Translate).

Next: :doc:`build`.