myGengo Python Library (for the myGengo API)
Translating your tools and products helps people all over the world access them; this is, of course, a somewhat tricky problem to solve. myGengo is a service that offers human-translation (which is often a higher quality than machine translation), and an API to manage sending in work and watching jobs. This is a python interface to make using the API simpler (some would say incredibly easy).
Installing myGengo is fairly simple:
pip install mygengo
Alternatively, if you're in the stone ages:
easy_install mygengo
myGengo also relies on httplib2, which can be installed through either of the above methods. If you're running on a version of Python prior to 2.6, you'll need to install simplejson as well.
A version of myGengo for Python 3 is in the works, but as Python 3 isn't even quite deemed production ready/reliable yet, it's not the highest priority at the moment.
myGengo has a full suite of Unit Tests. To run them, grab the source, head into the mygengo directory, and execute the tests file with the Python interpreter, ala:
python tests.py
If you have questions or comments and would like to reach us directly, please feel free to do so at the following outlets. We love hearing from developers!
Email: ryan [at] mygengo dot com
Twitter: @mygengo_dev
If you come across any issues, please file them on the Github project issue tracker. Thanks!
Full documentation of each function is below, but anyone should be able to cobble together a working script with the following:
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly false, depending on your dev needs
)
print gengo.getAccountBalance()
All function definitions can be found inside mygengo/mockdb.py. They exist as an uber dictionary: the key of the dictionary entry is the function name, and the parameters are exactly the same as specified over on the myGengo API docs.
Creates an instance of MyGengo for you to communicate with the myGengo API. This needs to be done before any of the methods below are available.
- public_key: Required. Your public key, generated on the myGengo API site.
- private_key: Required. Your private key, generated on the myGengo API site.
- sandbox: Optional. Defaults to False, dictates whethe to send the call to the myGengo Sandbox API.
- api_version: Optional. API version to use with myGengo (defaults to 1).
- headers: Optional. Additional HTTP headers to send along, passed as a dictionary object.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
Retrieves your account stats, like orders made, etc.
None
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
print gengo.getAccountStats()
Retrieves your account balance in myGengo credits.
None
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
print gengo.getAccountBalance()
Sends a new job over to myGengo for translation. Jobs are dictionaries that get passed around; an example is below.
- job: Required. A dictionary containing a full job description for myGengo (see below).
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
job = {
'type': 'text', # REQUIRED. Type to translate, you'll probably always put 'text' here. ;P
'slug': 'Single :: English to Japanese', # REQUIRED. Slug for internally storing, can be generic.
'body_src': 'Testing myGengo API library calls.', # REQUIRED. The text you're translating. ;P
'lc_src': 'en', # REQUIRED. source_language_code (see getServiceLanguages() for a list of codes)
'lc_tgt': 'ja', # REQUIRED. target_language_code (see getServiceLanguages() for a list of codes)
'tier': 'standard', # REQUIRED. tier type ("machine", "standard", "pro", or "ultra")
'auto_approve': 0, # OPTIONAL. Hopefully self explanatory (1 = yes, 0 = no),
'comment': 'HEY THERE TRANSLATOR', # OPTIONAL. Comment to leave for translator.
'callback_url': 'http://...', # OPTIONAL. Callback URL that updates are sent to.
'custom_data': 'your optional custom data, limited to 1kb.' # OPTIONAL
}
gengo.postTranslationJob(job = job)
Submits a job or group of jobs to translate.
- jobs: Required. A Dictionary of jobs and associated properties to run up to myGengo.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
data = {
'jobs': {
'job_1': {
'type': 'text', # REQUIRED. Type to translate, you'll probably always put 'text' here. ;P
'slug': 'Single :: English to Japanese', # REQUIRED. Slug for internally storing, can be generic.
'body_src': 'Testing myGengo API library calls.', # REQUIRED. The text you're translating. ;P
'lc_src': 'en', # REQUIRED. source_language_code (see getServiceLanguages() for a list of codes)
'lc_tgt': 'ja', # REQUIRED. target_language_code (see getServiceLanguages() for a list of codes)
'tier': 'standard', # REQUIRED. tier type ("machine", "standard", "pro", or "ultra")
'auto_approve': 0, # OPTIONAL. Hopefully self explanatory (1 = yes, 0 = no),
'comment': 'HEY THERE TRANSLATOR', # OPTIONAL. Comment to leave for translator.
'callback_url': 'http://...', # OPTIONAL. Callback URL that updates are sent to.
'custom_data': 'your optional custom data, limited to 1kb.' # OPTIONAL
},
'job_2': {
'type': 'text', # REQUIRED. Type to translate, you'll probably always put 'text' here. ;P
'slug': 'Single :: English to Japanese', # REQUIRED. Slug for internally storing, can be generic.
'body_src': 'Testing myGengo API library calls.', # REQUIRED. The text you're translating. ;P
'lc_src': 'en', # REQUIRED. source_language_code (see getServiceLanguages() for a list of codes)
'lc_tgt': 'ja', # REQUIRED. target_language_code (see getServiceLanguages() for a list of codes)
'tier': 'standard', # REQUIRED. tier type ("machine", "standard", "pro", or "ultra")
'auto_approve': 0, # OPTIONAL. Hopefully self explanatory (1 = yes, 0 = no),
'comment': 'HEY THERE TRANSLATOR', # OPTIONAL. Comment to leave for translator.
'callback_url': 'http://...', # OPTIONAL. Callback URL that updates are sent to.
'custom_data': 'your optional custom data, limited to 1kb.' # OPTIONAL
},
},
'process': 1, # OPTIONAL. 1 (true, default) / 0 (false). Whether to pay for the job(s) and make them available for translation.
'as_group': 1, # OPTIONAL. 1 (true) / 0 (false, default). Whether all jobs in this group should be done by one translator.
}
# Post over our two jobs, use the same translator for both, don't pay for them
gengo.postTranslationJobs(jobs = data)
Note: 'as_group' has a catch: some restrictions apply to what jobs can be grouped, including the requirement that language pairs and tiers must be the same across all jobs.
Determine how much it'll cost to translate a given piece of text/copy. A method that believes it's a POST, even though it very much seems like a GET. Bears a striking similarity to MyGengo.postTranslationJobs().
- jobs: Required. An Dictionary of Jobs to run up to myGengo.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
jobs_data = {
'job_1': {
'type': 'text', # REQUIRED. Type to translate, you'll probably always put 'text' here. ;P
'slug': 'Single :: English to Japanese', # REQUIRED. Slug for internally storing, can be generic.
'body_src': 'Testing myGengo API library calls.', # REQUIRED. The text you're translating. ;P
'lc_src': 'en', # REQUIRED. source_language_code (see getServiceLanguages() for a list of codes)
'lc_tgt': 'ja', # REQUIRED. target_language_code (see getServiceLanguages() for a list of codes)
'tier': 'standard', # REQUIRED. tier type ("machine", "standard", "pro", or "ultra")
'auto_approve': 0, # OPTIONAL. Hopefully self explanatory (1 = yes, 0 = no),
'comment': 'HEY THERE TRANSLATOR', # OPTIONAL. Comment to leave for translator.
'callback_url': 'http://...', # OPTIONAL. Callback URL that updates are sent to.
'custom_data': 'your optional custom data, limited to 1kb.' # OPTIONAL
},
'job_2': {
'type': 'text', # REQUIRED. Type to translate, you'll probably always put 'text' here. ;P
'slug': 'Single :: English to Japanese', # REQUIRED. Slug for internally storing, can be generic.
'body_src': 'Testing myGengo API library calls.', # REQUIRED. The text you're translating. ;P
'lc_src': 'en', # REQUIRED. source_language_code (see getServiceLanguages() for a list of codes)
'lc_tgt': 'ja', # REQUIRED. target_language_code (see getServiceLanguages() for a list of codes)
'tier': 'standard', # REQUIRED. tier type ("machine", "standard", "pro", or "ultra")
'auto_approve': 0, # OPTIONAL. Hopefully self explanatory (1 = yes, 0 = no),
'comment': 'HEY THERE TRANSLATOR', # OPTIONAL. Comment to leave for translator.
'callback_url': 'http://...', # OPTIONAL. Callback URL that updates are sent to.
'custom_data': 'your optional custom data, limited to 1kb.' # OPTIONAL
},
}
# Post over our two jobs, use the same translator for both, don't pay for them
gengo.determineTranslationCost(jobs = jobs_data)
Updates an existing job. A bit of a hamburger method in that you can cook this one many different ways - pay attention to the parameter specifications.
- id: Required. The ID of the job you're updating.
- action: Required. A dictionary describing the actions you are performing on this job ("purchase", "revise", "approve", "reject"). Some of these actions require other parameters, see their respective sections immediately below.
None
- comment: Optional. A comment describing the revision.
- rating: Required. 1 - 5, 1 = ohgodwtfisthis, 5 = I want yo babies yo,
- for_translator: Optional. Comments that you can pass on to the translator.
- for_mygengo: Optional. Comments to send to the myGengo staff (kept private on myGengo's end)
- public: Optional. 1 (true) / 0 (false, default). Whether myGengo can share this feedback publicly.
- reason: Required. Reason for rejection (must be "quality", "incomplete", "other")
- comment: Required. Explain your rejection, especially if all you put was "other".
- captcha: Required. The captcha image text. Each job in a "reviewable" state will have a captcha_url value, which is a URL to an image. This captcha value is required only if a job is to be rejected. If the captcha is wrong, a URL for a new captcha is also included with the error message.
- follow_up: Optional. "requeue" (default) or "cancel". If you choose "requeue" the job will be rejected and then passed onto another translator. If you choose "cancel" the job will be completely cancelled upon rejection.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
# Some example action objects, choose one to test by uncommenting
updateObj = {'action': 'purchase'}
# updateObj = {'action': 'revise', 'comment': 'Thanks but no thanks'}
# updateObj = {'action': 'approve', 'rating': 1, 'for_translator': 'Thanks!'}
# updateObj = {'action': 'reject', 'reason': 'quality', 'comment': 'My grandmother does better.', 'captcha': 'bert'}
gengo.updateTranslationJob(id = 42, action = updateObj)
Updates multiple existing jobs. A bit of a hamburger method in that you can cook this one many different ways - pay attention to the parameter specifications.
- id: Required. The ID of the job you're updating.
- action: Required. A dictionary describing the actions you are performing on these job ("purchase", "revise", "approve", "reject"). Some of these actions require other parameters, see their respective sections immediately below.
None
- comment: Optional. A comment describing the revision.
- rating: Required. 1 - 5, 1 = ohgodwtfisthis, 5 = I want yo babies yo,
- for_translator: Optional. Comments that you can pass on to the translator.
- for_mygengo: Optional. Comments to send to the myGengo staff (kept private on myGengo's end)
- public: Optional. 1 (true) / 0 (false, default). Whether myGengo can share this feedback publicly.
- reason: Required. Reason for rejection (must be "quality", "incomplete", "other")
- comment: Required. Explain your rejection, especially if all you put was "other".
- captcha: Required. The captcha image text. Each job in a "reviewable" state will have a captcha_url value, which is a URL to an image. This captcha value is required only if a job is to be rejected. If the captcha is wrong, a URL for a new captcha is also included with the error message.
- follow_up: Optional. "requeue" (default) or "cancel". If you choose "requeue" the job will be rejected and then passed onto another translator. If you choose "cancel" the job will be completely cancelled upon rejection.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
# Some example action objects, choose one to test by uncommenting
updateObj = {'action': 'purchase'}
# updateObj = {'action': 'revise', 'comment': 'Thanks but no thanks'}
# updateObj = {'action': 'approve', 'rating': 1, 'for_translator': 'Thanks!'}
# updateObj = {'action': 'reject', 'reason': 'quality', 'comment': 'My grandmother does better.', 'captcha': 'bert'}
gengo.updateTranslationJob(id = 42, action = updateObj)
Retrieves a specific job from mygengo.
- id: Required. The ID of the job you want to retrieve.
- pre_mt: Optional. 1 (true) / 0 (false, default). Whether to return a machine translation if the human translation is not complete yet.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getTranslationJob(id = 42, pre_mt = 1)
Retrieves a list of resources for the most recent jobs filtered by the given parameters.
- status: Optional. "unpaid", "available", "pending", "reviewable", "approved", "rejected", or "canceled".
- timestamp_after: Optional. Epoch timestamp from which to filter submitted jobs.
- count: Optional. Defaults to 10.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getTranslationJobs(status = "unpaid", count = 15)
Retrieves the group of jobs that were previously submitted together.
- id: Required. The ID of a job that you're looking for the entire batch of.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getTranslationJobBatch(id = 42)
Submits a new comment to the job's comment thread.
- id: Required. The ID of the translation job to comment on.
- comment: Required. A dictionary with the body/text of your comment.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.postTranslationJobComment(id = 42, comment = {
'body': 'I love lamp!',
})
Retrieves the comment thread for a job.
- id: Required. The ID of the translation job you're retrieving comments from.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getTranslationJobComments(id = 42)
Retrieves the feedback you have submitted for a particular job.
- id: Required. The ID of the translation job you're retrieving comments from.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getTranslationJobFeedback(id = 42)
Gets list of revision resources for a job. Revisions are created each time a translator or Senior Translator updates the text.
- id: Required. The ID of the translation job you're getting revisions from.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getTranslationJobRevisions(id = 42)
Gets a specific revision for a job.
- id: Required. The ID of the translation job you're getting revisions from.
- rev_id: Required. The ID of the revision you're looking up.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getTranslationJobRevision(id = 42, rev_id = 1)
Returns a GIF preview image of the translated text.
- id: Required. The ID of the translation job you want a preview image for.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getTranslationJobPreviewImage(id = 42)
Cancels the job. You can only cancel a job if it has not been started already by a translator.
- id: Required. The ID of the job you want to delete.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.deleteTranslationJob(id = 42)
Cancels multiple jobs. You can only cancel a job if it has not been started already by a translator.
- id: Required. The ID of the job you want to delete.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.deleteTranslationJobs(ids = [42, 43, 44, 56])
Returns a list of supported languages and their language codes.
None
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
gengo.getServiceLanguages()
Returns supported translation language pairs, tiers, and credit prices.
- lc_src: Optional. A source language code to filter the results to relevant pairs.
from mygengo import MyGengo
gengo = MyGengo(
public_key = 'your_public_key',
private_key = 'your_private_key',
sandbox = True, # possibly False, depending on your dev needs
)
# Send along an optional source language declaration.
gengo.getServiceLanguagePairs(lc_src = 'en')
Convenience method for making sure that text is in an acceptable format for myGengo submissions.
- text: Required. Text to convert.
from mygengo import MyGengo
# Make this into a UTF-8 encoded string...
MyGengo.unicode2utf8("私は")