feat: add JSON example

Author: daniel-jones-dev

CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+### Added
+* Add [example](examples/json) to translate JSON inputs. 
+
+
 ## [1.13.0] - 2023-01-26
 ### Added
 * Add [example script](examples/mustache) to translate Mustache templates.
@@ -234,6 +239,7 @@ Version increased to avoid conflicts with old packages on PyPI.
 Initial version.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-python/compare/v1.13.0...HEAD
 [1.13.0]: https://github.com/DeepLcom/deepl-python/compare/v1.12.0...v1.13.0
 [1.12.0]: https://github.com/DeepLcom/deepl-python/compare/v1.11.0...v1.12.0
 [1.11.0]: https://github.com/DeepLcom/deepl-python/compare/v1.10.0...v1.11.0

examples/json/README.md

@@ -0,0 +1,64 @@
+# Example: Translation of JSON values
+
+An example showing how to translate strings within JSON objects.
+
+The script translates strings, but leaves numbers, booleans, null values and
+object keys untranslated. It also recurses into arrays and objects.
+
+For example:
+
+```
+{
+  "greeting": "Good morning!",
+  "messages": [
+    "This is a message.",
+    {
+      "text": "Here is an embedded text.",
+      "sent": false
+    },
+    null
+  ],
+  "active": true,
+  "balance": 100.0
+}
+```
+
+could be translated into German as:
+
+```
+{
+  "greeting": "Guten Morgen!",
+  "messages": [
+    "Dies ist eine Nachricht.",
+    {
+      "text": "Hier ist ein Text eingebettet.",
+      "sent": false
+    },
+    null
+  ],
+  "active": true,
+  "balance": 100.0
+}
+```
+
+## Usage
+
+Install the [`deepl` Python library](../../README.md).
+
+Define your DeepL auth key as an environment variable `DEEPL_AUTH_KEY`.
+
+```
+export DEEPL_AUTH_KEY=f63c02c5-f056-...
+```
+
+Run the JSON translator by running Python on this directory:
+
+```
+python examples/json --to de '{"greeting": "Hello!"}'
+```
+
+For an explanation of the command line arguments, provide the `--help` option:
+
+```
+python examples/json --help
+```

examples/json/__main__.py

@@ -0,0 +1,90 @@
+# Copyright 2023 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+
+import argparse
+import deepl
+import os
+
+from translate_json import translate_json
+
+
+env_auth_key = "DEEPL_AUTH_KEY"
+env_server_url = "DEEPL_SERVER_URL"
+
+
+def get_parser(prog_name):
+    """Constructs and returns the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog=prog_name,
+        description="Translate strings in JSON using the DeepL API "
+        "(https://www.deepl.com/docs-api).",
+        epilog="If you encounter issues while using this example, please "
+        "report them at https://github.com/DeepLcom/deepl-python/issues",
+    )
+
+    parser.add_argument(
+        "--auth-key",
+        default=None,
+        help="authentication key as given in your DeepL account; the "
+        f"{env_auth_key} environment variable is used as secondary fallback",
+    )
+    parser.add_argument(
+        "--server-url",
+        default=None,
+        metavar="URL",
+        help=f"alternative server URL for testing; the {env_server_url} "
+        f"environment variable may be used as secondary fallback",
+    )
+    parser.add_argument(
+        "--to",
+        "--target-lang",
+        dest="target_lang",
+        required=True,
+        help="language into which the JSON strings should be translated",
+    )
+    parser.add_argument(
+        "--from",
+        "--source-lang",
+        dest="source_lang",
+        help="language of the JSON strings to be translated",
+    )
+    parser.add_argument(
+        "json",
+        nargs="+",
+        type=str,
+        help="JSON to be translated. Wrap JSON in quotes to prevent "
+        "the shell from splitting on whitespace.",
+    )
+
+    return parser
+
+
+def main():
+    # Create a parser, reusing most of the arguments from the main CLI
+    parser = get_parser(prog_name=None)
+    args = parser.parse_args()
+    auth_key = args.auth_key or os.getenv(env_auth_key)
+    server_url = args.server_url or os.getenv(env_server_url)
+    if auth_key is None:
+        raise Exception(
+            f"Please provide authentication key via the {env_auth_key} "
+            "environment variable or --auth_key argument"
+        )
+
+    # Create a Translator object, and call get_usage() to validate connection
+    translator = deepl.Translator(auth_key, server_url=server_url)
+    translator.get_usage()
+
+    for json in args.json:
+        output = translate_json(
+            json,
+            translator=translator,
+            source_lang=args.source_lang,
+            target_lang=args.target_lang,
+        )
+        print(output)
+
+
+if __name__ == "__main__":
+    main()

examples/json/translate_json.py

@@ -0,0 +1,94 @@
+# Copyright 2023 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+
+import deepl
+import json
+import logging
+from typing import Any, Callable, List, Tuple
+
+
+def batch_translate(
+    input_handler_pairs: List[Tuple[str, Callable[[deepl.TextResult], None]]],
+    target_lang: str,
+    translator: deepl.Translator,
+    **kwargs,
+) -> None:
+    """
+    Takes a list of translation inputs and result handlers, translates all
+    inputs and calls each handler with the translation results.
+    """
+    inputs = [input_str for input_str, _ in input_handler_pairs]
+    handlers = [handler for _, handler in input_handler_pairs]
+    results = translator.translate_text(
+        inputs, target_lang=target_lang, **kwargs
+    )
+    for result, handler in zip(results, handlers):
+        handler(result)
+
+
+def parse_json_for_translation(
+    obj: Any,
+    translation_candidates: List[
+        Tuple[str, Callable[[deepl.TextResult], None]]
+    ],
+):
+    """
+    Steps into the given JSON object and adds all strings to
+    translation candidates list
+    """
+
+    if type(obj) is dict:
+        keys = obj.keys()
+    elif type(obj) is list:
+        keys = range(len(obj))
+    else:
+        return
+
+    for key in keys:
+        if type(obj[key]) is str:
+            current_obj = obj
+            current_key = key
+            assign = lambda val: current_obj.__setitem__(current_key, val.text)
+            translation_candidates.append((obj[key], assign))
+        else:
+            parse_json_for_translation(obj[key], translation_candidates)
+
+
+def translate_json(
+    json_input: str,
+    target_lang: str,
+    translator: deepl.Translator,
+    **kwargs,
+) -> str:
+    """
+    Translates given JSON input using DeepL Translator.
+
+    Most of the arguments of the translate_text function are supported,
+    source_lang, target_lang, glossary_id, formality, etc.
+
+    :param json_input: JSON input to be translated.
+    :param target_lang: language code to translate template into, for example
+        "DE", "EN-US", "FR".
+    :param translator: deepl.Translator to use for translation.
+    :return: Translated JSON.
+    """
+
+    logger = logging.getLogger("deepl")
+    obj = json.loads(json_input)
+    # Wrap the JSON object in an array, in case the input is a string
+    obj = [obj]
+
+    # Find all text in the JSON that is to be translated
+    translation_candidates = []
+    parse_json_for_translation(obj, translation_candidates)
+    logger.info(
+        f"Found {len(translation_candidates)} strings to be translated"
+    )
+
+    # Translate all texts
+    batch_translate(translation_candidates, target_lang, translator, **kwargs)
+    logger.info("Translation complete")
+
+    # Unwrap the dummy array and convert to JSON
+    return json.dumps(obj[0])