Skip to main content

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:

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:

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.

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.