This method lets you include existing translated content with the actual source content to translate. It is all about "alignment"...
The key use cases for sending translations are:
To achieve this you would issue three API calls, to send source content, translated content and alignment instructions, all in this precise order:
All three API methods are actually the same but with different content and locale parameter.
URL
(PUT) /api/files/file?token=&locale=&folder=&filename=
Please note that this is an HTTP PUT and not a GET action. The binary data of the file must be included in the message body. Please note that multi-part attachments are not supported.
This method is equivalent to copying a file to the project's "OUT\{target locale}" directory.
Parameters are:
token | The session token obtained when connecting. |
locale | The target language. This must be one of the project target languages. Language codes are ISO 2 letter codes such as “en”, “fr”, “en-GB”, “en-US”, etc. |
filename | The relative path of the file including sub-directories.
Note the use of backslash separators as it is common on Windows systems. The file will be saved to the project output directory inside the target language folder. All sub-directories in the file name are created if these do not yet exist. Using sub-directories is useful if you want to organize files into folders. |
folder | It's possible to also specify the folder in param or as a string in filename Can be null |
MESSAGE BODY | Add the binary content (xml, Word, etc) to the message body. Set content type to "Stream", such as in: Content-Type: Stream Do not use multi-part MIME contents as this is not supported by the Beebox. |
Always make sure to verify the HTTP status to make sure that your operation succeeded.
The file will be saved to the project output directory. Example: If you send content for language "fr-FR" and filename “folder1\myfile.xml”, the file will be saved to “c:\beebox\{project id}\out\fr-FR\folder1\myfile.xml”.
The method returns no result. An HTTP status of 204 indicates success.
Other HTTP status values indicate an error.
Your source language is Japanese. You want to send the Japanese page "pages\page1.html" for translation and include an existing translated Spanish web page. The sequence of calls is:
/api/files/file?token=...&filename=pages\page1.html.beebox&locale=ja MESSAGE BODY: { "locales": ["es"], "align": { "locales": ["es"] } } ) /api/files/file?token=...&filename=pages\page1.html&locale=es MESSAGE BODY: The existing Spanish html code - The translation /api/files/file?token=...&filename=pages\page1.html&locale=ja MESSAGE BODY: The original Japanese html code |
Note that the first call sends the instructions. The "locale" is the source language. The second call is the translated content and "locale" is Spanish. The third call is the original content and the "locale" is Japanese. Internally, all these files will be saved to the Beebox project directory in these locations:
c:\Beebox\{project key} \in \pages\page1.html \pages\page1.html.beebox \out \es \pages\page1.html |
The "pages" subdirectory is a folder included in the "filename" parameter above.
The c:\Beebox root directory may be different in your setup.
The actual content you include with your API call can be of any encoding (code page).
You can, but do not need, to "normalize" original text content to UTF-8 or similar. The Beebox, if properly configured, is capable of reading any code pages.
If you actually generate text content on the fly in PHP, Java etc. it is best practice to encode in UTF-8 for maximum language support.
If you send files from disk, it is best to send as binary content. Binary formats such as Microsoft Word or Adobe InDesign are sent unchanged obviously.
After files were added they will be scanned by beebox. To retrieve last scan date, you should execute following method.
(GET) /api/files/status?token=
Parameters are:
token | The session token obtained when connecting. |
A typical result may look like:
{ "lastScan": "2020-03-06T09:20:48.1194058Z", "lastSourceFileChange": "2020-03-06T09:20:39.7131728Z", "scanRequired": false } |