UI Recommendations

This document will help you implement a UI for your API connection to myGengo. If you need more information refer to our Translation API documentation (especially System Overview, API First Steps and Best Practices for Plugins & API Usage), or contact support.

Things to remember when implementing a UI for myGengo translation

• Make it clear to the user when they place an order that the translation will cost money
• Use the natural workflow of your app — only add extra panels if you have to
• Stick to myGengo UI terminology wherever possible for consistency (as users may also use e.g. the myGengo web interface)
  • …but make sure UI terms make sense to your users
• If using placeholder machine pre-translation, make it clear to the user when the content is machine translated
• Include help information from myGengo (or links to it) where possible
• Keep it simple

What myGengo-related panels should your app have?

Your app will need to display various panels, with content going back and forth to myGengo. Here are the recommended panels based on the myGengo API, with example wireframes. See myGengo’s web interface and the myGengo API Lab competition winners for example implementations.

Note: While you can combine or omit some panels, ensure your myGengo implementation covers the core functions (order, review, approve) and is easy for your users.

Panels

Order translation panel

The user confirms the settings for translating some content and places an order (a job, a group of jobs, or multiple jobs)

Translation jobs overview list

The user can see the status of their translation jobs

Pending job panel

The user can cancel the job, and optionally see placeholder machine translation, and/or the job’s estimated translation time

Comment thread panel

The user can see comments regarding a job, optionally with previous versions of the translation

Comment submission panel

The user can send a comment to the job’s translator

Translation job review panel

The user can accept a completed job, or potentially request corrections, reject the job, or provide feedback when accepting the job

Feedback panel

The user can provide feedback when accepting a completed translation (as part of the translation job review panel), and optionally add the translator to a “preferred translators” list

Approved translation panel

The user can see information about a job they approved, including the translated text

Request revisions panel

The user can formally request a correction, choosing a reason and submitting a comment

Job rejection panel

After successfully passing captcha the user can reject a translation (passing the job to a new translator), or optionally reject and cancel the translation. The user must choose a reason for the rejection and submit feedback.

Settings panel

The user can specify settings related to translation

Views

Note: Refer to the Translate API - Job Payload and Translate API Methods documentation for more information.

Order translation panel (essential)

In this view the user will confirm the settings for translating one (or more) pieces of content and place an order. Depending on your app this might be a step in a publishing process, a part of another panel, or an individual panel within your system. You can allow the user to bundle a group of translations with the same settings together (a group of jobs), and to order multiple translations with different settings at the same time. Refer to the translate/jobs (POST) method and Translate API - Job Payload for more information.

The following apply per job or group of jobs:

Required

• Allow the user to select the source and target languages (lc_src and lc_tgt respectively)
• Allow the user to select the translation tier, including machine translation (tier)
• Indicate the content to be translated (body_src)
• Display the unit count of the content to be translated (excluding units inside [[[…]]])
• Show the price at the chosen translation tier for the job or group of jobs (= unit price of language pair at selected translation tier × translatable unit count)

Note: Users can wrap any text they don’t want translated in [[[…]]] (triple square brackets). For example, in “My teacher gave us [[[ 7 apples ]]] today”, the phrase “7 apples” won’t be translated. This feature is quite popular, so let your users know about it if possible.

Caution: If calculating unit count and price, don’t include units inside [[[…]]].

Recommended

• Suggest the source language by pre-checking the content to be translated
• Allow the user to add a comment for the translator (comment)
• Allow the user to order multiple jobs, or a group of jobs, at once
  • Allow the user to order a group of jobs with the same translation settings (as_group)
    • Preferably pre-set this according to the UI of your app, e.g. for a blog post include the post’s title, body and keywords fields as a group of jobs
  • Allow the user to request translations in multiple languages in a single order (by creating one job per target language)
• If there’s more than one job show the order’s total price

If possible

• Allow the user to set automatic job approval per job (auto_approve)
• Show the estimated translation time (eta)
• An option to use preferred translators, per job/group of jobs or per order (use_preferred)

Note:Preferred translators are translators the user has indicated they’d prefer to use again in a previous job’s feedback form, after evaluating the translator’s output. For a language pair, the user must have selected at least two preferred translators before this option is available.

Translation jobs overview (essential)

This shows the current status of all translations that have been ordered through myGengo (ref: translate/jobs (GET) method and Job payload response). You might make it a separate page, or simply add the information from myGengo to an existing UI. Content management systems often have a list of all articles, which can be a good place to add it.

The following apply per job or group of jobs:

Required

• Status (status)
• Timestamp when job was received by myGengo (ctime)
• Translation tier (tier)
• Source and target languages (lc_src and lc_tgt respectively)
• Unit count (word count, or character count for CKJ languages) (unit_count)
• Price (credits)

Recommended

• Job # (job_id)
• Timestamp when the job was last updated with a comment or status change
• Number of comments
• “Cancel” button (if the job or group of jobs has the status available or unpaid)

If possible

• Indicate when there are unread comments
• Show the estimated completion time (eta)

Pending job panel

Depending on your app, you may choose to show pending translations (a status of available, pending, or unpaid) simply as normal data within your system, or you may wish to show them on their own specific page. If you do choose to have a discrete page, we recommend you also show the comment thread panel on this page.

Required

• Allow the user to cancel an available or unpaid translation (pending jobs can not be cancelled)

Recommended

• Show the submitted text (body_src)
• Show the estimated completion time (eta)

If possible

• Show a machine translation (body_tgt)

Comment thread panel

The comment thread panel displays comments from the user, translator(s) and myGengo support regarding a job or group of jobs.

Required

• Show comments, including the following info per-comment:
  • Comment (body)
  • Author (author)
  • Timestamp (ctime)

Recommended

• Display comments from myGengo customer support differently
• Show or link to previous revisions in the comment thread

Comment submission panel

If a comment submission form is not provided in your app, we recommend including a link to the job’s details page on myGengo, using the URL http://mygengo.com/translate/job/details/{id}.

Required

• Comment field (body)
• “Submit” button
• Warn users not to submit or request personal details
• Prevent empty comment submission

Translation job review panel (essential)

The translation job review panel allows the user to check a completed translation, and potentially approve it. The translation is provided as a raw JPEG image stream (673px wide) and as tall as required via translate/job/{id}/preview (GET). We recommend you also allow them to reject or request corrections for a job (via translate/job/{id} (PUT)).

Required

• Image preview of the translated text (via translate/job/{id}/preview (GET))
• “Approve” button

Recommended

• Job # (job_id)
• Content submitted (body_src)
• Comment thread panel (incorporated into the review panel, or as a separate linked panel)
• “Reject” button (→ Job rejection panel)
• “Request corrections” button (→ Request revisions panel)
• Show a group of jobs together
• Include the feedback form panel (associated with the “Approve” button)

If possible

• Show or link to previous revisions in the comment thread (via translate/job/{id}/revisions (GET))
• Make the “Approve” button the most prominent

Feedback panel (as part of the Job review panel)

The feedback panel allows users to formally rate and comment on the translation (job or group of jobs) when they approve it. This is very valuable feedback that helps us improve myGengo’s service. You can also allow the user to add the translator to their preferred translators list. Currently the feedback form needs to be included within the job review form, as feedback is sent within the approve call using translate/job/{id} (PUT) approve.

Recommended

• Rating (rating, single choice)
  • Include the rating guideline matrix — 1 (poor) to 5 (fantastic)
• Feedback for translator (for_translator)
• Feedback for myGengo staff (for_mygengo, private)
• Allow the user to choose whether myGengo may use the translation as a public example (public)

If possible

• Allow the user to add the translator to their preferred translators list

Approved job panel

Depending on your app, you may choose to show approved jobs simply as normal data within your system, or you may wish to show them in their own specific panel.

Required

• The translated text (body_tgt)

Recommended

• The original text (body_src)
• Any feedback submitted (rating, for_translator, for_mygengo)

If possible

• Comment thread (via translate/job/{id}/comments (GET))
• Show or link to previous revisions in the comment thread (via translate/job/{id}/revisions (GET))

Request revisions panel

The request revisions panel allows the user to request revisions from the job’s translator. If an in-app form is not provided, we recommend including a link to the job details page on myGengo, using the URL http://mygengo.com/translate/job/details/{id}.

Required

• Comment field to let the translator know the reason(s) for requesting revisions, in as much detail as possible (comment)
• “Request revisions” button

Recommended

• Include myGengo’s revisions instructions
• Include link to the myGengo FAQ (see “When should I reject a job? When should I request corrections?”)
• Remind the user to write the comment in the source language or target language

Job rejection panel

The job rejection panel allows the user to reject a specific job, and requires that the user answer a simple captcha to verify the rejection. If an in-app form is not provided, we recommend including a link to the job details page on myGengo, using the URL http://mygengo.com/translate/job/details/{id}.

Required

• Reason for rejection (from presets “quality”, “incomplete”, “other”) (reason)
• Comment field to explain the reason for rejection (comment)
• Captcha image
• Captcha text field (captcha)
• “Reject” button (by default this will pass the job to another translator, follow_up = "requeue")

Recommended

• Ask user if they would like to use the request revisions instead
• Include myGengo’s rejection instructions
• Include link to the myGengo FAQ (see “When should I reject a job? When should I request corrections?”)
• Change “Reject” button to “Reject and reopen”, and add a “Reject and close” button (follow_up = "cancel")

Settings panel

The settings panel allows the user to set their public and private API keys, and define default settings for job orders. You may also place other settings information in this page that is specific to how your app works with the myGengo API. For instance you may allow the user to set the default translation tier for new jobs. The user might not change these settings themselves — they may be set centrally or through a configuration file.

Required

• Update API public key
• Update API private key

Potential options

• Use preferred translators by default
• Approve all jobs automatically
• Set a custom email notification address