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

CODE

(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: You obtain a key when calling projects/{did}/documents/offline/import/init (GET) You use the key to upload your file or your files using media/filescollection 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: true : Read and save any changes to the project document in the system. This is the normal behavior. false : Read but do not save changes. This is useful during debugging, or, to just find out what changes the files contain. 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: true : Update target segment even when it is locked. false : Do not update target segment when it is locked. Recommended behavior. 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:

JS

{
  "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

JSON

{
    "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. CODE `{ "count": 2, "fatal": 0, "files": [ .... ] }` The object has these properties: count: The total number of imported files fatal: The total number of invalid files. For error details, see the files-property. files: An array with details for each imported file. See further below for all 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. To download a report use media/filescollection/{key}/items/file with this key and the filename. To first inspect all available reports, optionally use media/filescollection/{key}/items with this key. The reports are of the following format and contents: When importing an XLIFF file: The report is an Excel file (.xlsx) with one row per imported translation unit. See “Reports” section on this page for details. When importing a Microsoft Word file: The report is the exact same Word file but includes status information such as errors or unchanged translations. When importing a Microsoft Excel file: The report is the exact same Excel file but includes status information such as errors or unchanged translations. 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: CODE `"file": "Doc1.docx (en.de).xliff", "report": "Doc1.docx (en.de).xliff.report.xlsx"`	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: CODE `{ "isfatal": true, "fatal": "The Microsoft Word document could not be read. Please make sure it is not corrupt or password protected.", "fatalDetails": null, ... }`	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: type: The internal code for the field. title: The name/title of the field. count: The total changes such as the total number of updated German translations. 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. true: Yes all identified changes were saved to the system. If commit is was set to true. false: No, changes were not saved. We are executing this method in preview mode. If commit is was set to false.	bool
importUpdated	The actual number of segments updated in the system. This excludes segments counted under importConflicts Usually the same as status.changes, it may be that you set parameter writeLocked to true. This prevents saving changes to a locked segment.	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.