projects/{did}/documents/offline/import (POST)
Import back translated documents that had previously been exported for offline work using the export method.
A complete import requires these steps:
Initialise the import using projects/{did}/documents/offline/import/init (GET)
Upload the file(s) to import using media/filescollection/{key}/items/file (POST)
Call the present method to execute the import and obtain a detailed report of changes and issues.
URL
(POST) /api/projects/{pid}/documents/offline/import
PARAMETERS
The URL parameters are:
pid | The project ID | int, Mandatory |
The body must contain a JSON object with these properties:
filesKey | This key references the files you must have uploaded previous to calling the present method:
The present method will fail if the key is invalid or expired or the files collection contains no files or invalid files. | string, Mandatory |
commit | Boolean that indicates:
Most often, changes refer to translations. However, Wordbee allows to update many other meta information including the status, bookmarks, comments and more. | bool, Mandatory |
writeLocked | Boolean that indicates:
Which option to choose will depend on your specific case and if a project manager locks segments with the purpose to strictly prevent any further updates. | bool, Mandatory |
callbackurl, callback | Specify a URL which will be called upon success or failure of operation. This makes polling for operation status unnecessary. See Callbacks (with asynchronous operations) | Optional |
RESULTS
The API method returns an Asynchronous operation result:
{
"trm": {
"requestid":32230,
"status":"Waiting",
"statusText":"Waiting..."
}
}
You can poll the status or use the callback parameter. When the operation is complete, the results are in the custom property
{
"trm": {
"requestid": 32230,
"isbatch": false,
"status": "Finished",
"statusText": "Finished!"
},
"custom": {
[ ****** RESULTS ****** ]
}
}
The custom property is a JSON object:
results | A JSON object with a summary of import results and status. The object has these properties:
|
|
reportsFilesKey | Key of the files collection that contains a report per each imported file. There will be one report per item in the results.files array.
The reports are of the following format and contents:
Hint: In a typical user interface you would let end users download these reports. It gives translators or project managers all the details needed to evaluate if the imported files are correct, complete or not.
| string |
commit | Boolean. Same value as you specified in the payload. | bool |
writeLocked | Boolean. Same value as you specified in the payload. | bool |
Files collection (results.files)
Each file has these properties:
file | The uploaded file name. | string |
report | The report file name. IMPORTANT: To download the report use report and not file for the filename parameter. The report filename includes the language codes and may have a different file extension. Example:
| string |
status | An object with import status details. | object |
status.isfatal | Boolean. If true then the file could is not in any valid format or not an originally exported file. | bool |
status.fatal | Error message if isfatal is true. Example:
| string? |
status.fatalDetails | - | object[]? |
status.total | Total segments in file. | int |
status.processed | Total segments in file that were actually processed. Segments that are not processed are segments. Note: status.total and status.processed should generally be identical. They are not, if the translator added invalid segments/rows to the files (e.g. rows that were not originally exported). | int |
status.errors | Total processed segments that contain errors. | int |
status.changes | Total processed segments that were actually updated. For example, if a user changed the translation or a meta information or added a comment, etc. | int |
status.nochanges | The total of unchanged segments which is equivalent to: status.processed - status.changes. | int |
status.fieldChanges | This property gives statistical information of which fields (translation, status, custom field, comments…) were changed or added. Each element has these properties:
Note: This property may not be available with all export file formats. | object[] |
importExecuted | Indicates if changes were saved to the system or not. This depends on the commit parameter.
| bool |
importUpdated | The actual number of segments updated in the system.
| int |
importConflicts | The number of segments that could not be updated due to some concurrent changes done by another API or an online user. If this value is different from 0 (which very likely it will never be) you might want to rerun the operation. | int |
REPORTS
WHEN IMPORTING XLIFF FILE
The report is an Excel (xlsx) with one row per translation unit:
The Location is the position of the translation unit in the file.
The Segment id is the Wordbee segment identifier (such as used in the translation editor).
The Type may be any of:
Changed: The translation or other meta data have been updated. See “Details” for a description of what precisely was updated.
Unchanged: There was no change detected in the imported file. The segment is not updated.
Error : The changes cannot be imported. The reason will be printed in the “Details” column.
WHEN IMPORTING WORD FILE
The report is a clone of the imported file but adds detailed update and error information per each segment.
WHEN IMPORTING EXCEL FILE
The report is a clone of the imported file but adds detailed update and error information per each segment.
TIPS & TRICKS
You can track the API call sequence and contents easily from the Wordbee Translator user interface. Go to a Standard project and click the “Export” button in the “Work & Delivery” page:
You will be able to see the API methods and payloads in Google Chrome in the developer console:
Important note: The UI polls the asynchronous operation with a proxy web service (“/Poll”) and not the API 2 method that you would use. The result is still almost identical but the JSON payload is string-encoded.
Copyright Wordbee - Buzzin' Outside the Box since 2008