Versions Compared

Version Old Version 9 New Version 10
Changes made by

Stephan Böhmig

Stephan Böhmig

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The request BODY contains a JSON object with these properties:

files

An array with containing one or more records, each describing a file to be uploaded. The These records include the a unique token referencing an the uploaded a file. ExampleFor example:

Code Block
[
    {
        "token": "77ca3562-ff01f5882dd1",
        "name": "myfolder/myfile.docx"
    }
]

See detailed description further down.

object[], Mandatory

src

The source language code. This must be a valid project language.

string, Mandatory

trgs

The languages to translate to. These must be valid project languages. Example:

Code Block
"trgs": [ "es-ES", "fr-FR" ]

string[], Mandatory

deadline

Optional deadline for completion of work. Deadlines are assigned to the jobs that are created with the workflow. Example:

Code Block
"deadline": "2024-04-03T06:00:00Z"

datetime?, Optional

workflow

Optional, selects "Default" if not specified. Fine-tune how workflows are created:

  • Default : Create jobs according to the project’s Workflow & Suppliers configuration. Recommended value.

  • None : Do not create any jobs.

string, Optional

allowUpdates

Optional. Default is true.

  • true: You are allowed to replace existing files with new versions. In such cases, the file is replaced, a new set of jobs will be created and the new jobs will be assigned to the same workers as before.

  • false: Any attempt to replace an existing file will return an error.

bool?, Optional

jobsCfs

Optional custom fields to assign to all jobs created for a file’s workflow. See Custom Field Collection Record for details. Note: You reference a CF by either its “id” or its “name”.

Example:

Code Block
"fields": [
    { "title": "Activity", "value": "Fulltime" },
    { "id": 4, "value": "A-221" }    
  ]

object[], Optional

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

...

This method is an asynchronous operation: Your request is queued and executes will execute as soon as possible.

Info

Asynchronous operations - How to:

The API method immediately returns a JSON object that includes the ID of the operation - (look for the requestId property).

However, it the operation has not yet been executed. You will need to await the operation’s termination in order to get obtain results.

Waiting can be done in two ways: Either you regularly poll for : Polling: Regularly check the operation’s status, or you wait for a webhook call. The latter is . Webhook Call: Wait for a callback using the callbackurl parameter you may want to add in your request. We definitely strongly recommend the latter approach. Please read For more details, please refer to the documentation: Asynchronous operations for more details.

The JSON results, obtained with polling or with a callback, includes include the operation status as well as any results specific to the API method. Below is an example for of successful termination:

Code Block
 {
    "trm": {
        "requestid": 13432,
        "isbatch": false,
        "status": "Finished",
        "statusText": "Finished!"
    },
    "custom": {
        "files": [
            {
                "name": "file-003.htm",
                "format": {
                    "formatId": 7952,
                    "formatName": "Default",
                    "formatDomain": "HTML"
                },
                "exists": false,
                "success": true,
                "error": null,
                "did": 288981,
                "segments": 87
            }
        ],
        "request": {
            ...
        }
    }
}

...

  • files: The list of files you submitted

  • src: The source locale

  • trgs: List of target locales.

  • projectId: The project ID.

  • resourceId: The project memory ID.

  • etc.

ERROR HANDLING

Correct and complete Effective error handling will require some efforts. There are involves careful consideration and effort. Let’s break it down into three levels of errors:

Invalid payload

Immediate

If you submit an invalid payload, your API call will immediately be rejected with the error payload typical for the API. Here is an example when submitting an invalid source locale:

Code Block
{
  "error": {
    "operation": null,
    "date": "2024-04-03T15:57:01.2110105Z",
    "title": "Invalid parameter 'src': Invalid source locale"
  },
  "reason": "Invalid parameter 'src': Invalid source locale"
}

Resolution: You likely need to fix your payload.

Operation failed

Delayed

If your payload is valid, your request is now queued. If the operation then fails with a fatal error, you get the async error payload. For example:

Code Block
{
    "trm": {
        "requestid": 559,
        "isbatch": false,
        "status": "Failed",
        "statusText": "Operation failed!",
        "statusInfo": "The parameter xy was not properly supplied"
    }
}

Resolution: Depending on the error message. You should not see such issues often. If the error details are unclear you may need to reach out to Wordbee support.

Operation ok but file failed

Delayed

The operation may have executed just fine but a submitted file (or several) could not be processed. The file specific error will be listed in the results, look for success and error:

Code Block
"custom": {
        "files": [
            {
                "name": "file-003.htm",
                "format": {
                    "formatId": 7952,
                    "formatName": "Default Gemini",
                    "formatDomain": "HTML"
                },
                "exists": false,
                "success": false,
                "error": "Failed to process file. No segments.",
                "did": null,
                "segments": null
            }
        ]

Resolution: Depending on the message. You likely face one of these issues:

  • The file is invalid and failed to process. Think of a badly formatted XML file. Please check your files test manually in Wordbee Translator.

  • The file name is invalid, such as too long or contains invalid characters. Please fix file naming conventions.

  • The file contains 0 segments. Please do not submit empty files, Wordbee does not like them.

...