API - Send instructions

When you send a file to translate, the Beebox will translate according to the configured workflow and automation. By default, the translation will be into all project target languages.

Next to the source file, you can optionally send JSON formatted "instructions" to the Beebox:

Specify the target languages of translation. For example: Translate file into French only ("fr").
Specify a deadline of translation.
Specify text alignment options in case you also sent the translated file version.
Specify any meta information to include files.

Read: When to use instructions?.

URL

(PUT) /api/files/file?token=&locale=&folder=&filename={source file name}.beebox

Add JSON formatted instructions to the request body. Note that the instructions file is named like the source file name + .beebox at the end.

The API method, parameters, and result is identical to that for sending source files.

Instruction file name and location

The instructions are stored are JSON formatted. Let us suppose the source file is folder\document-200.xml. In that case, the instructions file must be named folder\document-200.xml.beebox . Append “.beebox” to the original file name like in the example below:

To request a translation into one specific target language, send a JSON like below with name "document-200.xml.beebox":

{ "locales": ["es-ES"] }

Use the standard API call to send: /api/files/file?token=...&filename=document-200.xml.beebox&locale=en

Instructions format

Instructions are JSON files saved in UTF-8 format. It may contain one or more of the following options:

Example

CODE

{
    "translate": true,
	"deadline": "2015-11-08T23:00:00.0000000Z",
	"locales": ["fr-BE", "es"],
	"align": { "locales": ["fr-BE"] },
	"metadata": [ 
		{ "id": "url", "value": "http://mine.com/page199.htm", "type": "segment" },
		{ "id": "title", "value": "Introduction page", "type": "segment", "title": "Top title" },
		{ "id": "reference", "value": "A-1024", "type": "segment", "title": "Page reference" }
		],
	"unapproveAll": false,
	"disableMT": false,
	"diableJobs": false,
	"attachments": ["filePath", "filePath"]
}

JSON properties

Instruction	Sample JSON
translate	Optional boolean. Specifies whether the file shall be translated or not. If omitted, the value is assumed "true". Generally, you would not include this property.
deadline	Specify an ISO formatted deadline. The value may include a time zone indicator. In the example below we use "Z" to indicate the UTC time zone. CODE `"deadline": "2015-11-08T23:00:00.0000000Z"` Optional field. If not specified, the source file will not be given a specific deadline for translation.
deadlineLocal	Optional. Specify a deadline in the Beebox server's local time zone. The format must be exactly as in the example below. Do not use both "deadline" and "dealineLocal" at the same time. CODE `"deadlineLocal": "2015-06-15T13:00:00"` Optional field. If not specified, the source file will not be given a specific deadline for translation.
locales	Specifies one or more target languages for translation. Most content management system connectors send files with one specific target language, like in: CODE `"locales": [ "de-DE" ]` Optional field. If not specified, the system assumes that the file requires translation into ALL the project target languages.
align	Instructs the Beebox to look for translated files in the Beebox "out" directory. If translated files are found, these will be aligned with the source file for the purpose of pretranslation. The JSON indicates the target languages for which to look for translated files. CODE `"locales": [ "de-DE", "de-AT", "fr" ]` Optional field. If not specified, the system will not align the source and translated files. This option has a common use case with content management system connectors. Imagine that a user edits translations in the CMS directly. To capture such edits and send to the translation team, you would simply send this to the Beebox: (a) the source page, (b) the edited page, (c) instructions telling the Beebox to align source/edited page. All edits of the user will be extracted by the Beebox and send to the translation team for approval or revision.
unapproveAll	Instructs the Beebox to force unapproval of any pretranslations. There is one specific use case for setting this property: Imagine that you retrieve a translated file from the Beebox. The user looks at it and does not like it at all. In that case you can propose an option to send the original file once again to the Beebox (maybe you include the translated file too for alignment) with the property "unapprove" set to true. If you do not set the flag then the Beebox will immediately return to you the very same translated file since the source text did not change and the Beebox already has the translations in its memory. With the flag set, the Beebox will do all pretranslation as well but flag them as unapproved. This means the content goes into the regular human translation workflow once again for editing. CODE `"unapproveAll": false` Optional. If not included, no unapproved is enforced.
metadata	Permits to include any kind of meta-data with each source file: CODE `"metadata": [ { "id": "url", "value": "http://mine.com/page199.htm", "type": "file", "title": "Page URL" }, { "id": "title", "value": "Introduction page", "type": "segment" } ]` The properties are: "id": An alphanumeric id for the meta data element "value": The meta data content "title": An option user friendly title. In Beebox meta information is labelled with the reference or the title, if the latter is specified. It is recommended to always set a title. "type": A mandatory value: "segment": Segment meta data is stored with each source segment of the file. This data can be viewed inside Beebox and is exported to XLIFF or to Wordbee Translator custom fields. "file": Information referring to the entire file. It is exported to XLIFF (attribute in <file> node) or Wordbee Translator (as a comment attached to the file). Meta information in translation jobs: Wordbee Translator jobs Meta data are inserted as either file or segment level comments in Wordbee Translator. These are instantly visible in the Wordbee translation editor. at file level: The metadata will be visible in the Job dashboards of the system (main job dashboard and project-dashboard of the project linked to Beebox). You will need to pass this information to the Job custom fields in the Wordbee Beebox link. at segment level: One comment is added per each meta data item. The comment shows "title" property and "value" properties. This information will be available within the Editor, just as shown below: Note that pass through projects supports file-level metadata only. As seen above, regular Beebox projects allow you to populate Wordbee Translator custom fields in segments or jobs. For this to work, you need to include a segment or file-level metadata and follow a special convention for the "id" property: "CustomStr1", "CustomStr2", etc. These are the IDs used in Wordbee Translator for segment level data. Make sure to first configure corresponding segment level custom fields in Wordbee. XLIFF jobs Meta information is included with XLIFF jobs as described here. Additional reading: Please read this page more information and alternative approaches of adding metadata.
disableMT	If true then machine translation is explicitly disabled for this file. Optional. If not included then MT is enabled if used in the workflow.
disableJobs	If true then human workflows (translation, revision...) are explicitly disabled for this file. Optional. If not included then human work is enabled if used in the workflow.
attachments	The attachment files, if existing, are attached to the Wordbee job references. This feature is available with Pass-Through projects only. It is not supported by regular Beebox projects.

Common use cases

Please read the use cases. Instructions files are an important tool!

API call sequence

Always send files in this order to the Beebox:

The instructions file, if any
The translated file, if any
The source file

It is important to send the source file at the end or otherwise an automatic Beebox operation might detect and process the source file before you start sending instructions and translations.

CONTENT ENCODING AND CODE PAGES

Serialize JSON to UTF-8 when adding to the HTTP request body.

ADDITIONAL INFORMATION

More information is found at:

When to use instructions files

Meta information

Beebox also supports folder level instruction files:

Folder and File instructions