Allow dictionaries as translation sources

Author: csvtuda

README.md

@@ -158,37 +158,37 @@ Library    ${CURDIR}/PluginLib.py    plugins=${CURDIR}/MyPlugin.py
 
 # Translation
 
-PLC supports translation of keywords names and documentation, but arguments names, tags and types
-can not be currently translated. Translation is provided as a file containing
-[Json](https://www.json.org/json-en.html) and as a
-[Path](https://docs.python.org/3/library/pathlib.html) object. Translation is provided in
-`translation` argument in the `HybridCore` or `DynamicCore` `__init__`. Providing translation
-file is optional, also it is not mandatory to provide translation to all keyword.
+PLC supports translation of keywords names and documentation. Translations must be provided as 
+[JSON](https://www.json.org/json-en.html) data in the `translation` argument in the `HybridCore` 
+or `DynamicCore` `__init__`, either directly or through a 
+[Path](https://docs.python.org/3/library/pathlib.html) to a file. Providing translation data is 
+optional, also it is not mandatory to provide translation to all keyword.
 
 The keys of json are the methods names, not the keyword names, which implements keyword. Value
 of key is json object which contains two keys: `name` and `doc`. `name` key contains the keyword
 translated name and `doc` contains keyword translated documentation. Providing
 `doc` and `name` is optional, example translation json file can only provide translations only
-to keyword names or only to documentatin. But it is always recomended to provide translation to
+to keyword names or only to documentation. But it is always recommended to provide translation to
 both `name` and `doc`.
 
-Library class documentation and instance documetation has special keys, `__init__` key will
-replace instance documentation and `__intro__` will replace libary class documentation.
+Library class documentation and instance documentation has special keys, `__init__` key will
+replace instance documentation and `__intro__` will replace library class documentation.
+
+> [!NOTE]
+> Arguments names, tags and types can not be currently translated.
 
 ## Example
 
 If there is library like this:
 ```python
-from pathlib import Path
-
 from robotlibcore import DynamicCore, keyword
 
 class SmallLibrary(DynamicCore):
     """Library documentation."""
 
-    def __init__(self, translation: Path):
+    def __init__(self):
         """__init__ documentation."""
-        DynamicCore.__init__(self, [], translation.absolute())
+        DynamicCore.__init__(self, [])
 
     @keyword(tags=["tag1", "tag2"])
     def normal_keyword(self, arg: int, other: str) -> str:
@@ -212,8 +212,22 @@ class SmallLibrary(DynamicCore):
         return some + other
 ```
 
-And when there is translation file like:
-```json
+And we want to translate it as follows:
+
+- keyword `normal_keyword` to `other_name`
+  - its documentation to `This is new doc`
+- keyword `name_changed` to `name_changed_again`
+  - its documentation to `This is also replaced.\n\nnew line.`.
+- the library constructor documentation to `Replaces init docs with this one.`
+- the library documentation to `New __intro__ documentation is here.`
+
+
+### Provide Translation As File
+
+To provide the translation as a file, simply pass the path to a JSON file containing the translations:
+
+```jsonc
+// my_translation.json
 {
     "normal_keyword": {
         "name": "other_name",
@@ -230,12 +244,76 @@ And when there is translation file like:
     "__intro__": {
         "name": "__intro__",
         "doc": "New __intro__ documentation is here."
-    },
+    }
 }
 ```
-Then `normal_keyword` is translated to `other_name`. Also this keyword documentions is
-translted to `This is new doc`. The keyword is `name_changed` is translted to
-`name_changed_again` keyword and keyword documentation is translted to
-`This is also replaced.\n\nnew line.`. The library class documentation is translated
-to `Replaces init docs with this one.` and class documentation is translted to
-`New __intro__ documentation is here.`
+
+```python
+from pathlib import Path
+
+class SmallLibrary(DynamicCore):
+    """Library documentation."""
+
+    def __init__(self):
+        """__init__ documentation."""
+        DynamicCore.__init__(self, [], translation=Path("/path/to/my_translation.json"))
+
+    # ...
+```
+
+> [!IMPORTANT]
+> Translation files passed as paths must always be in JSON format.
+
+### Provide Translation As Dictionary
+
+You can also pass the translation data as a dictionary:
+
+```python
+import json
+from pathlib import Path
+
+class SmallLibrary(DynamicCore):
+    """Library documentation."""
+
+    def __init__(self):
+        """__init__ documentation."""
+        translation_data = json.loads(Path("/path/to/my_translation.json").read_text(encoding="utf-8"))
+        DynamicCore.__init__(self, [], translation=translation_data)
+
+    # ...
+```
+
+This also allows you to use other data formats such as YAML:
+
+```yaml
+normal_keyword:
+  name: other_name
+  doc: This is new doc
+name_changed:
+  name: name_changed_again
+  doc: |
+    This is also replaced.
+
+    new line.
+__init__:
+  name: __init__
+  doc: Replaces init docs with this one.
+__intro__:
+  name: __intro__
+  doc: New __intro__ documentation is here.
+```
+
+```python
+import yaml
+from pathlib import Path
+
+class SmallLibrary(DynamicCore):
+    """Library documentation."""
+
+    def __init__(self, translation_file: Path):
+        """__init__ documentation."""
+        translation_data = yaml.safe_load(translation_file.read_text(encoding="utf-8"))
+        DynamicCore.__init__(self, [], translation=translation_data)
+
+    # ...
+```

atest/SmallLibrary.py

@@ -1,5 +1,5 @@
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Union
 
 from robot.api import logger
 from robotlibcore import DynamicCore, keyword
@@ -14,12 +14,14 @@ def execute_something(self):
 class SmallLibrary(DynamicCore):
     """Library documentation."""
 
-    def __init__(self, translation: Optional[Path] = None):
+    def __init__(self, translation: Optional[Union[Path, dict]] = None):
         """__init__ documentation."""
-        if not isinstance(translation, Path):
+        if isinstance(translation, (dict, Path)):
+            DynamicCore.__init__(self, [KeywordClass()], translation)
+        else:
             logger.warn("Convert to Path")
             translation = Path(translation)
-        DynamicCore.__init__(self, [KeywordClass()], translation.absolute())
+            DynamicCore.__init__(self, [KeywordClass()], translation.absolute())
 
     @keyword(tags=["tag1", "tag2"])
     def normal_keyword(self, arg: int, other: str) -> str:

atest/tests_types.robot

@@ -2,11 +2,13 @@
 Library     DynamicTypesLibrary.py
 Library     DynamicTypesAnnotationsLibrary.py    xxx
 Library     SmallLibrary.py    ${CURDIR}/translation.json
+Library     SmallLibrary.py    ${ALL_TRANSLATIONS}    AS    TranslatedLibraryDict
 
 
 *** Variables ***
 ${CUSTOM NONE} =    ${None}
-
+&{TRANSLATION_1}=    name=Name Changed Through Dict    doc=A translated docstring.
+&{ALL_TRANSLATIONS}=    name_changed=${TRANSLATION_1}
 
 *** Test Cases ***
 Keyword Default Argument As Abject None
@@ -122,6 +124,10 @@ SmallLibray With New Name
     ${data} =    SmallLibrary.name_changed_again    1    2
     Should Be Equal As Integers    ${data}    3
 
+TranslatedLibraryDict With New Name
+    ${data} =    TranslatedLibraryDict.Name Changed Through Dict    1   2
+    Should Be Equal As Integers    ${data}    3
+
 
 *** Keywords ***
 Import DynamicTypesAnnotationsLibrary In Python 3.10 Only

src/robotlibcore/core/hybrid.py

@@ -22,7 +22,7 @@
 
 
 class HybridCore:
-    def __init__(self, library_components: list, translation: Path | None = None) -> None:
+    def __init__(self, library_components: list, translation: Path | dict | None = None) -> None:
         self.keywords: dict = {}
         self.keywords_spec: dict = {}
         self.attributes: dict = {}

src/robotlibcore/utils/translations.py

@@ -19,14 +19,16 @@
 from robot.api import logger
 
 
-def _translation(translation: Path | None = None):
-    if translation and isinstance(translation, Path) and translation.is_file():
+def _translation(translation: Path | dict | None = None):
+    if isinstance(translation, Path) and translation.is_file():
         with translation.open("r", encoding="utf-8") as file:
             try:
                 return json.load(file)
             except json.decoder.JSONDecodeError:
                 logger.warn(f"Could not convert json file {translation} to dictionary.")
                 return {}
+    elif isinstance(translation, dict):
+        return translation
     else:
         return {}
 

utest/test_translations.py

@@ -1,13 +1,19 @@
+import json
 from pathlib import Path
 
 import pytest
 from SmallLibrary import SmallLibrary
 
 
-@pytest.fixture(scope="module")
-def lib():
+@pytest.fixture(scope="module", params=["path", "dict"])
+def lib(request):
     translation = Path(__file__).parent.parent / "atest" / "translation.json"
-    return SmallLibrary(translation=translation)
+    if request.param == "path":
+        return SmallLibrary(translation=translation)
+    if request.param == "dict":
+        json_data = json.loads(translation.read_text(encoding="utf-8"))
+        return SmallLibrary(translation=json_data)
+    raise ValueError(request.param)
 
 
 def test_invalid_translation():
@@ -59,9 +65,7 @@ def test_kw_not_translated_but_doc_is(lib: SmallLibrary):
     assert doc == "Here is new doc"
 
 
-def test_rf_name_not_in_keywords():
-    translation = Path(__file__).parent.parent / "atest" / "translation.json"
-    lib = SmallLibrary(translation=translation)
+def test_rf_name_not_in_keywords(lib: SmallLibrary):
     kw = lib.keywords
     assert "Execute SomeThing" not in kw, f"Execute SomeThing should not be present: {kw}"
     assert len(kw) == 6, f"Too many keywords: {kw}"