When to use instructions files

When sending source files for translation to the Beebox, you may optionally include JSON formatted instructions. These provide additional information to the Beebox on how to process the source content. Before you continue, please read about sending instructions files.

Instructions files are commonly used in these cases:

Send file for translation into specific language

Most CMS connectors send content individually per target language.

Example: A user selects English pages to translate into French and Spanish. Most connector will proceed by sending the source files twice, i.e. once per target language. With each source file, the instructions contain the target language. The sequence of calls would be:

/api/files/file?token=...&filename=pages\fr\page10.xml.beebox&locale=en (instructions is { "locales": ["fr"] } )
/api/files/file?token=...&filename=pages\fr\page10.xml&locale=en 		(include source page in body)
/api/files/file?token=...&filename=pages\es\page10.xml.beebox&locale=en	(instructions is { "locales": ["es"] } )
/api/files/file?token=...&filename=pages\es\page10.xml&locale=en 		(include source page in body)

You can see that the developer included the target language in the file's name to avoid conflicts.

Alternatively, you could also send source files just once like in the example below.

/api/files/file?token=...&filename=pages\page10.xml.beebox&locale=en 
		{ "locales": ["fr", "es"] } )
/api/files/file?token=...&filename=pages\page10.xml&locale=en 		(include source page in body)

The approach you chose is yours, both work fine.

Transmit translated content (to capture user edits and annotations)

Top CMS connectors propose a great functionality to content managers: They let them proofread, annotate and edit translations inside the CMS. The user is then given the possibility to send the edits/annotations to the translation team. Is this not much better than informing the translators about errors by email?

To achieve this, you need to send the translated content to the Beebox. It will then read out the changes and annotations and forward to the translation team.

/api/files/file?token=...&filename=pages\page10.xml.beebox&locale=en (instructions is 
			{ "locales": ["fr"], "align": { "locales": ["fr"] } } )
/api/files/file?token=...&filename=pages\page10.xml&locale=fr (include translated page in body)
/api/files/file?token=...&filename=pages\page10.xml&locale=en (include source page in body)

Note the order of sending: First instructions, then translation, then source.

Enable users to reject translations entirely

Use the "approveAll" option if a user entirely rejects a translation and expects the translation team to redo the work. You may want to a button in the CMS connector saying "Translation must be redone - Add to cart again"

Typically you would then also include the translations when resending (see option above). It may well be that the user rejects all translations but did some edits or added annotations.

Enable users to specify a deadline

Most CMS connectors let a user fill in an optional deadline when sending content to the Beebox. The deadline will be transmitted to the translation team by the Beebox.