The SameGoal Translation API allows districts to translate student documents from English (en) to other languages (Spanish (es), Nepali (ne), etc) using a third-party translation vendor of their choice.

Process link

Setup link

  1. District administrator contracts with a third-party translation vendor.
  2. District administrator generates an API access token using their SameGoal administrator account and provides this token to the vendor.
  3. Vendor calls the SameGoal Translation Registration API with this token to activate the translation integration service for this district.

Document Translation Workflow link

  1. A user in the district requests a document is translated from within the SameGoal web application.
  2. The district administrator is notified within SameGoal of the translation request and approves or denies it.
  3. If approved, SameGoal submits the document to be translated to the vendor via the Translation Request API.
  4. After completing the translation, the vendor returns the translated document using the Translation Complete API.
  5. The translated document is displayed within the SameGoal web application.

API link

The SameGoal Translation API is a REST API built on top of JSON (JavaScript Object Notation) and XLIFF (XML Localization Interchange File Format).

Registration link

An example Registration request:

POST https://samegoal.com/api/v1/translationRegistration
Authorization: Bearer sg_auth_token
Content-Type: application/json

{ "address": "https://vendor.com/translationRequest", "token": "vendor_auth_token" }

To complete registration for a given district with SameGoal, the vendor must POST to the /api/v1/translationRegistration endpoint. The body of the HTTP request must contain a JSON object with an address and token field. The address field is a URL hosted by the vendor. SameGoal will POST an HTTP request to this URL each time a document should be translated. The token field is an opaque string generated by the vendor (vendor_auth_token) which SameGoal will pass to the vendor as a "Bearer token" on all requests. The vendor must pass the district-provided access token (sg_auth_token) as an HTTP "Bearer token" on all requests to the SameGoal API.

lightbulb_outline TIP
The Translation Request endpoint address and vendor_auth_token must be activated and ready for use prior to sending a registration request. The reason for this requirement is that an empty Translation Request is performed in the background prior to Registration completing successfully. If the background Translation Request fails, the corresponding Registration will also fail. In the event of a Registration failure, it is the responsibility of the translation vendor to attempt registration again later.

lightbulb_outline TIP
Future calls to Registration supersede previous calls. To update your address URL or token (vendor_auth_token), simply Register again. In the simple case, a vendor only needs to Register once.

Translation Request link

An example Translation Request request:

POST https://vendor.com/translationRequest
Authorization: Bearer vendor_auth_token
Content-Type: application/json

[{"id": "1546462623111432448_60", "xliff": "doc_xliff"}, ...]

Documents in SameGoal are incrementally requested and approved for translation. When approvals are received, SameGoal will POST the document to be translated to the Translation Request endpoint provided by the vendor in the address field at Registration.

SameGoal will send a JSON array with zero or more items in the body of each Translation Request. Each item in the array is a JSON object with two fields. Field id is a unique identifier for the translation request. Other than assuming it is unique, the vendor should treat the id as an opaque string. The document to be translated is provided in the xliff field.

lightbulb_outline TIP
Each Translation Request may contain 0 or more documents. During Registration, as well as intermittently, SameGoal may send empty Translation Requests to ensure the endpoint is still responsive. These empty requests must return HTTP 200 OK and corresponding JSON: {"code":200, "message":"OK"}.

The xliff field contains the document to be translated in industry standard XLIFF 2.1. All ids should be treated as opaque identifiers. The document should be translated into the language specified in the trgLang attribute on the <xliff> element.

An example doc_xliff, for which the entire document should be translated, may contain the following. Note the global translate="yes" annotation on the <file>.

<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.1" srcLang="en" trgLang="es">
 <file id="1546462623111432448_60" translate="yes">
  <unit id="/2/0/4/0/0/31:1546463007491/0">
   <segment>
    <source>[English text]</source>
   </segment>
  </unit>
  <unit id="/2/0/4/0/0/22/0" type="fmt">
   <segment>
    <source>[HTML content containing English text]</source>
   </segment>
  </unit>
 </file>
</xliff>

If a previously translated document is amended, only the subset of the document that was modified needs to be translated again. In this case, SameGoal sends a new Translation Request specifying translate="no" on the <file> and explicit translate="yes" annotations on the specific <unit>s that must be re-translated. SameGoal will also include the translated <target> elements in case they are helpful to the vendor in updating the translation. However, the vendor should only modify the <target> elements associated with <unit>s that are explicitly requested for translation.

<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.1" srcLang="en" trgLang="es">
 <file id="1546462623111432448_60" translate="no">
  <unit id="/2/0/4/0/0/31:1546463007491/0">
   <segment>
    <source>[English text]</source>
    <target>[Spanish test]</target>
   </segment>
  </unit>
  <unit id="/2/0/4/0/0/22/0" type="fmt" translate="yes">
   <segment>
    <source>[HTML content containing English text]</source>
    <target>[Previous Spanish translation]</source>
   </segment>
  </unit>
 </file>
</xliff>

lightbulb_outline TIP
Note that the <unit>s with type="fmt" contain HTML and must be translated accordingly.

lightbulb_outline TIP
If an HTTP 200 OK is not received when sending the vendor Translation Requests, SameGoal will intermittently attempt to resend the translation requests until too many successive failures occur. Therefore, it is possible a vendor receives multiple translation requests for a single document. To avoid duplicated translation work, a vendor must design its translation request handler to be idempotent. To do so, the vendor must ignore any requests for which the id has been previously received.

Translation Complete link

An example Translation Complete request:

POST https://samegoal.com/api/v1/translationComplete
Authorization: Bearer sg_auth_token
Content-Type: application/json

[{"id": "1546462623111432448_60", "xliff": "doc_xliff"}, ...]

After the translation vendor has completed the translation and populated the relevant <target> elements in the XLIFF document, the vendor must return the completed translation to SameGoal via the Translation Complete API. This is done by POSTing to the /api/v1/translationComplete endpoint. The body of the HTTP request must contain a JSON array with an item for each translated document. Each item is a JSON object with an id and xliff field.

lightbulb_outline TIP
In the event Translation Complete does not return HTTP 200 OK to the vendor, it is the responsibility of the vendor to re-submit the translation later. The Translation Complete handler is idempotent and will ignore duplicate submissions of translations.



.
.
.