A Jupyter notebook (hereafter just notebook, for short) is a type of document that contains executable code interspersed with visualizations of code execution results and narrative text.

Below we provide an example notebook which you may use as a starting point for designing your own experiments using language resources offered by PORTULAN CLARIN.

Pre-requisites

To execute this notebook, you need an access key you can obtain by clicking the button below. A key is valid for 31 days. It allows to submit a total of 5 million characters by means of requests with no more 2000 characters each. It allows to enter 100,000 requests, at a rate of no more than 200 requests per hour.

Request key

For other usage regimes, you should contact the helpdesk.

The input data sent to any PORTULAN CLARIN web service and the respective output will be automatically deleted from our computers after being processed. However, when running a notebook on an external service, such as the ones suggested below, you should take their data privacy policies into consideration.

Running the notebook

You have three options to run the notebook presented below:

1. Run on Binder — The Binder Project is funded by a 501c3 non-profit organization and is described in detail in the following paper:
   Jupyter et al., "Binder 2.0 - Reproducible, Interactive, Sharable Environments for Science at Scale."
   Proceedings of the 17th Python in Science Conference. 2018. doi://10.25080/Majora-4af1f417-011
2. Run on Google Colab — Google Colaboratory is a free-to-use product from Google Research.
3. Download the notebook from our public Github repository and run it on your computer.
   This is a more advanced option, which requires you to install Python 3 and Jupyter on your computer. For anyone without prior experience setting up a Python development environment, we strongly recommend one of the two options above.

LXTRANSLATOR_WS_API_KEY = 'access_key_goes_here'
LXTRANSLATOR_WS_API_URL = 'https://portulanclarin.net/workbench/lx-translator/api/'

try:
    import requests
except:
    !pip3 install requests
    import requests

class WSException(Exception):
    'Webservice Exception'
    def __init__(self, errordata):
        "errordata is a dict returned by the webservice with details about the error"
        super().__init__(self)
        assert isinstance(errordata, dict)
        self.message = errordata["message"]
        # see https://json-rpc.readthedocs.io/en/latest/exceptions.html for more info
        # about JSON-RPC error codes
        if -32099 <= errordata["code"] <= -32000:  # Server Error
            if errordata["data"]["type"] == "WebServiceException":
                self.message += f": {errordata['data']['message']}"
            else:
                self.message += f": {errordata['data']!r}"
    def __str__(self):
        return self.message

def translate(text, source, target):
    '''
    Arguments
        text: a string with a maximum of 2000 characters, Portuguese or Chinese
              text, with the input to be translated
        source: is a string specifying the source language, which can be either
               'zh' or 'pt'
        target: is a string specifying the target language, which can be either
               'zh' or 'pt' and must be different than source.
    
    Returns a string with the translation in the target language.
    Raises a WSException if an error occurs.
    '''

    request_data = {
        'method': 'translate',
        'jsonrpc': '2.0',
        'id': 0,
        'params': {
            'text': text,
            'source': source,
            'target': target,
            'key': LXTRANSLATOR_WS_API_KEY,
        },
    }
    request = requests.post(LXTRANSLATOR_WS_API_URL, json=request_data)
    response_data = request.json()
    if "error" in response_data:
        raise WSException(response_data["error"])
    else:
        return response_data["result"]

text = '''Esta frase serve para testar o funcionamento do tradutor. Esta outra
frase faz o mesmo.'''

result = translate(text, source="pt", target="zh")
print(result)

这句话用于测试翻译的运作。 另一个
这句话也是一样。

def get_key_status():
    '''Returns a string with the detailed status of the webservice access key'''
    
    request_data = {
        'method': 'key_status',
        'jsonrpc': '2.0',
        'id': 0,
        'params': {
            'key': LXTRANSLATOR_WS_API_KEY,
        },
    }
    request = requests.post(LXTRANSLATOR_WS_API_URL, json=request_data)
    response_data = request.json()
    if "error" in response_data:
        raise WSException(response_data["error"])
    else:
        return response_data["result"]

get_key_status()

{'requests_remaining': 99999996,
 'chars_remaining': 999999710,
 'expiry': '2030-01-10T00:00+00:00'}

The web service for this application is available at https://portulanclarin.net/workbench/lx-translator/api/.

Below you find an example of how to use this web service with Python 3.

This example resorts to the requests package. To install this package, run this command in the command line: pip3 install requests.

To use this web service, you need an access key you can obtain by clicking in the button below. A key is valid for 31 days. It allows to submit a total of 5 million characters by means of requests with no more 2000 characters each. It allows to enter 100,000 requests, at a rate of no more than 200 requests per hour.

Request key

For other usage regimes, you should contact the helpdesk.

The input data and the respective output will be automatically deleted from our computer after being processed. No copies will be retained after your use of this service.

import json
import requests  # to install this library, enter in your command line:
                 #  pip3 install requests

# This is a simple example to illustrate how you can use the LX-Translator web service

# Requires: key is a string with your access key
# Requires: text is a string, UTF-8, with a maximum 2000 characters, Portuguese text, with
#           the input to be processed
# Requires: source is a string specifying the source language, which can be either 'zh' or 'pt'
# Requires: target is a string specifying the target language, which can be either 'zh' or 'pt'
#           and must be different than source.

# Ensures: output according to specification in https://portulanclarin.net/workbench/lx-translator/
# Ensures: dict with number of requests and characters input so far with the access key, and
#          its date of expiry

key = 'access_key_goes_here' # before you run this example, replace access_key_goes_here by
                             # your access key


source = 'pt'
target = 'zh'
text = '''A nossa reunião está marcada.'''  # this string can be replaced by your input

# To read input text from a file, uncomment this block
#inputFile = open("myInputFileName", "r", encoding="utf-8") # replace myInputFileName by
                                                            # the name of your file
#text = inputFile.read()
#inputFile.close()


# Processing:

url = "https://portulanclarin.net/workbench/lx-translator/api/"
request_data = {
    'method': 'translate',
    'jsonrpc': '2.0',
    'id': 0,
    'params': {
        'text': text,
        'source': source,
        'target': target,
        'key': key,
    },
}
request = requests.post(url, json=request_data)
response_data = request.json()
if "error" in response_data:
    print("Error:", response_data["error"])
else:
    print("Result:")
    print(response_data["result"])


# To write output in a file, uncomment this block
#outputFile = open("myOutputFileName","w", encoding="utf-8") # replace myOutputFileName by
                                                             # the name of your file
#output = response_data["result"]
#outputFile.write(output)
#outputFile.close()


# Getting acess key status:

request_data = {
    'method': 'key_status',
    'jsonrpc': '2.0',
    'id': 0,
    'params': {
        'key': key,
    },
}
request = requests.post(url, json=request_data)
response_data = request.json()
if "error" in response_data:
    print("Error:", response_data["error"])
else:
    print("Key status:")
    print(json.dumps(response_data["result"], indent=4))