Add Translate transformer (#426)

* Add Translate transformer

* Replace packaging dependency with internal version handling (#425)

* Fix Translate transformer in older RF versions

* Apply suggestions from code review

Co-authored-by: Mateusz Nojek <matnojek@gmail.com>

Author: bhirsz

.github/workflows/unit-tests.yml

@@ -28,7 +28,7 @@ jobs:
             rf-version: 'stable5'
           - os: 'ubuntu-latest'
             python-version: '3.10'
-            rf-version: 'stable5'
+            rf-version: 'stable6'
     runs-on: ${{ matrix.os }}
 
     steps:

docs/releasenotes/3.3.rst

@@ -27,10 +27,19 @@ Or by using ``--language / --lang`` option::
 
 English language is supported by default.
 
+* New Translate transformer for translating Robot Framework files
 * Updated NormalizeSectionHeaderName transformer to work with translated headers
 * Updated MergeAndOrderSections to not merge language: <lang> header with other comment sections
 * Sections with only language: <lang> marker and less than ``section_lines`` empty lines will be not transformed by NormalizeNewLines
 
+Translate transformer
+----------------------
+
+Added new non-default transformer for translating Robot Framework files. It is possible to automatically convert your
+Robot Framework files to use other supported language.
+
+See the full documentation `here <https://robotidy.readthedocs.io/en/stable/transformers/Translate.html>`_.
+
 Fixes
 ------
 * Added missing ``--skip-comments`` option (#418)

docs/source/configuration/index.rst

@@ -43,6 +43,7 @@ Robot Framework version::
 
 It will disable all transformers that require Robot Framework greater than <target-version> to run (even if you have Robot Framework greater than <target-version> installed).
 
+.. _language_support:
 .. rubric:: Language support
 
 Robot Framework 6.0 added support for Robot settings and headers translation.

docs/source/transformers/Translate.rst

@@ -0,0 +1,141 @@
+.. _Translate:
+
+Translate
+================================
+
+Translate Robot Framework source files from one or many languages to different one.
+
+.. note::
+    Required Robot Framework version: >=6.0
+
+.. |TRANSFORMERNAME| replace:: Translate
+.. include:: disabled_hint.txt
+
+
+Example of Robot Framework markers translation:
+
+.. tab-set::
+
+    .. tab-item:: Before (default English)
+
+        .. code:: robotframework
+
+            *** Settings ***
+            Documentation    Dokumentacja zestawu
+
+            Library    Collections
+            Variables    vars.py
+
+            *** Test Cases ***
+            Pierwszy test
+                [Setup]    Setup Keyword
+                Step 1
+
+    .. tab-item:: After (translated to Polish)
+
+        .. code:: robotframework
+
+
+            *** Ustawienia ***
+            Documentation    Dokumentacja zestawu
+
+            Biblioteka    Collections
+            Zmienne    vars.py
+
+            *** Przypadki Testowe ***
+            Pierwszy test
+                [Inicjalizacja]    Setup Keyword
+                Step 1
+
+The language can be configured using ``language`` parameter with the language code (default ``en`` - English)::
+
+    robotidy --configure Translate:enabled=True:language=se
+
+Since the translation is from one or many languages to one, only one language can be configured.
+
+Source language
+----------------
+
+Robotidy will translate only markers that can be recognized. If your source file is written in different language
+you need to configure Robotidy to recognize given language. See :ref:`language_support` for more details.
+Following example configure Robotidy to read English, Polish and German languages and translate Robot Framework
+markers to Ukrainian::
+
+    robotidy --configure Translate:enabled=True:language:uk --language pl,de source_in_pl_and_de.robot
+
+BDD keywords
+-------------
+
+BDD keywords are not translated by default. Set ``translate_bdd`` parameter to ``True`` to enable it::
+
+    robotidy --configure Translate:enabled=True:translate_bdd=True files/
+
+.. tab-set::
+
+    .. tab-item:: Before (default English)
+
+        .. code:: robotframework
+
+            *** Test Cases ***
+            Test with BDD keywords
+                Given login page is open
+                When valid username and password are inserted
+                And credentials are submitted
+                Then welcome page should be open
+
+    .. tab-item:: After (translated BDD keywords to German)
+
+        .. code:: robotframework
+
+            *** Testfälle ***
+            Test with BDD keywords
+                Angenommen login page is open
+                Wenn valid username and password are inserted
+                Und credentials are submitted
+                Dann welcome page should be open
+
+Some language have more than one alternative to BDD keyword. For example Polish can use "Kiedy" or "Gdy" when
+translating "When" keyword. In this situation Robotidy will chose the first one (sorted alphabetically). It can
+be overwritten using  ``<bdd_keyword>_alternative`` parameters::
+
+    robotidy --configure Translate:enabled=True:language=pl:translate_bdd=True:when_alternative=Gdy files/
+
+Language headers
+-----------------
+
+Robotidy can add or replace existing language header in the files. For example, if you're translating file
+written in German to Swedish, the language header will change from ``language: de`` to ``language: se``.
+Translation to English will remove language header since it's not necessary.
+To do this configure ``add_language_header`` parameter to ``True``::
+
+    robotidy --configure Translate:enabled=True:add_language_header=True files/
+
+.. tab-set::
+
+    .. tab-item:: Before (default German)
+
+        .. code:: robotframework
+
+            # language: de
+
+            *** Testfälle ***
+            Test
+                Step
+
+    .. tab-item:: Translated to Swedish
+
+        .. code:: robotframework
+
+            # language: se
+
+            *** Testfall ***
+            Test
+                Step
+
+    .. tab-item:: Translated to English
+
+        .. code:: robotframework
+
+            *** Test Cases ***
+            Test
+                Step

noxfile.py

@@ -26,7 +26,7 @@ def unit(session, robot_version):
 
 @nox.session(python=DEFAULT_PYTHON_VERSION)
 def coverage(session):
-    install_dev_deps(session, "stable5")
+    install_dev_deps(session, "stable6")
     session.install("coverage")
     session.run("coverage", "run", "-m", "pytest")
     session.run("coverage", "html")

robotidy/config.py

@@ -3,6 +3,11 @@
 from pathlib import Path
 from typing import Dict, List, Optional, Pattern, Tuple
 
+try:
+    from robot.api import Languages  # RF 6.0
+except ImportError:
+    Languages = None
+
 from robotidy.files import get_paths
 from robotidy.transformers import load_transformers
 
@@ -81,7 +86,7 @@ def __init__(
         self.check = check
         self.output = output
         self.color = color
-        self.language = language
+        self.language = self.get_languages(language)
         transformers_config = self.convert_configure(transformers_config)
         self.transformers = self.get_transformers_instances(
             transformers, transformers_config, force_order, target_version, skip
@@ -91,6 +96,7 @@ def __init__(
             # inject global settings TODO: handle it better
             setattr(transformer, "formatting_config", self.formatting)
             setattr(transformer, "transformers", transformer_map)
+            setattr(transformer, "languages", self.language)
 
     @staticmethod
     def get_transformers_instances(transformers, transformers_config, force_order, target_version, skip):
@@ -107,3 +113,9 @@ def convert_configure(configure: List[Tuple[str, List]]) -> Dict[str, List]:
         for transformer, args in configure:
             config_map[transformer].extend(args)
         return config_map
+
+    @staticmethod
+    def get_languages(lang):
+        if Languages is None:
+            return None
+        return Languages(lang)