Page tree


If the API changes in an incompatible manner this is listed explicitly in the "important release notes" section of each releases changelog.

Provides access to the data of a single segment

URL:

/editor/taskid/[TaskId]/segment/[ID]

example:

/editor/taskid/774/segment/252190

Available Methods:

GET / PUT

Specialities:

Only possible with a task in edit mode. Resource Layout is dynamic.


Resource Layout

Name

Type

Info

id

int

GET only

fileId

int

GET only, set by import

isFirstofFilebooleanGET only, calculated depending on filters set

segmentNrInTask

int

GET only, set by import

userName

string

GET only, set by server

timestamp

date

GET only, set by server

editable

boolean

GET only, set by import

autoStateId

int

GET only, set by server

workflowStep

string

GET only, set by server

workflowStepNrintGET only, set by server

matchRate

int

initially set by import, should be changed only when new text content comes from a system which provides a new matchRate

matchRateTypestringinitially set by import to "import", should be changed when changing the above matchRate

durations

object


comments

string

GET only, set by server

qmId

string


stateId

int


[FIELD]

string

GET only

[FIELD]Edit

string

Optional, only if field is editable.

isWatchedboolean

GET only, set by server (user dependent)

segmentUserAssocIdint

GET only, set by server (user dependent)



Segments contain dynamic fields, defined on import. This dynamic fields contain the segment payload.

Additonal Meta Informations

In the JSON response you will find an additional object "metaData" beneath the normally used "rows" array. Currently metaData contains only the integer field "firstEditable" which contains the rowIndex of the first segment which is editable in the current sort and filtered segment list. This field is only returned in the first request.

Special URLs

URLMethodParametersDescription
/editor/segment/nextsegmentsPOST
next: boolean; 1 to find and return the next editable segment
nextFiltered: boolean; 1 to find and return the next editable segment filtered by workflow
prev: boolean; 1 to find and return the previous editable segment
prevFiltered: boolean; 1 to find and return the previous editable segment filtered by workflow
filter: the same filter parameters as for the segment listing
sort: the same sort parameters as for the segment listing
segmentId: integer; The ID of the segment which should be used as start point

In big tasks where only a few segments are editable,
it is possible that the requested segments (200 per page) does not contain the next or previous editable segment.

This information must then be calculated separately.
Since the calculation is expensive on DB side, this are separated requests, and not included in the normal GET segment calls.

The response contains a plain JSON Object, containing the segment IDs for the requested steps (next / nextFiltered / prev / prevFiltered).

For example (only next and nextFiltered were delivered with 1 (true) on the request):

{
	next: 123
	nextFiltered: 321
}
/editor/segment/termsPOSTid: integer; the segment id to get the terminology entries forreturns a HTML Fragment with the terminology entries of the requested segment.

Overview Segment Processing States (formerly known as AutoStates)

As they are shown in the GUI:

Complete list with description and when they are used.

IDSpeakable Name
(PHP Constant)
DescriptionRole / Workflow StepUsage
4NOT_TRANSLATEDNot translatedimportIs set on import time when source is set and target not. Is NOT set when translator deletes a previously translated segment.
0TRANSLATEDTranslated

import / translator

Set by the import process for pure Review Tasks for as initial segment state of translated segments or by translator when they work and translate a segment of a translation task.

Is used when the content of the segment is already translated at import time, or if a translator saves a segment with content and has written the content by himself or changed a match that he took from TM or MT.

14TRANSLATED_AUTOTranslated, autosettranslatorif a translator uses the repetition editor, the segments are getting this state.
15PRETRANSLATEDPretranslatedimport / translator

Is used on import when:

  • Import format defines the segment as pre-translated (corresponds with the pretrans flag of the segment then),
    for example for SDLXLIFF import when segment was auto-propagated and matchrate = 100%.
  • pre-translation within translate5 is used and the segment was pretranslated with translate5
  • A translator uses a language resource match and does not edit that afterwards (TODO)
3BLOCKED

Blocked

import / translator

Is used when a segment is not editable (defined by the imported data, or by translate5 Plug-Ins on custom criteria).

One default criteria in the import is the edit100%match setting in the task.
If edit100%match is false: (pre)translated segments with a >=100% match-rate are blocked and not editable in translate5.
If edit100%match is true: then such segments can be edited and are either in status pre-translated or translated.

Set either on import of pure review tasks, as defined by the imported data.

Is used if the translator uses a 100% match from a language resource and edit100%match is false. (TODO)

1REVIEWEDReviewedReviewer 1Is used when a reviewer saves a segment and has modified the content
2REVIEWED_AUTOReviewed, auto-setReviewer 1Is used like "Reviewed" but segment was saved via repetition editor instead of direct editing.
5REVIEWED_UNTOUCHEDReviewed, untouched, auto-set
at finish of workflow step
Reviewer 1If the last reviewer (review step 1) is finishing the task, all not reviewed (not touched) segments are set to this state automatically.
Can be disabled in the workflow action configuration, is enabled by default.
6REVIEWED_UNCHANGEDReviewed, untouchedReviewer 1Is used when the segment was opened and saved without any change. This marks the segment as "OK" by the reviewer (review step 1)
7REVIEWED_UNCHANGED_AUTOReviewed, untouched, auto-setReviewer 1Is used like above "Reviewed, unchanged" but segment was saved via repetition editor instead of direct editing.
8REVIEWED_TRANSLATORReviewed by 2nd reviewerReviewer 2Optional second review step: is set if the segment was changed manually in the second review step again
9REVIEWED_TRANSLATOR_AUTOReviewed by 2nd reviewer, auto-setReviewer 2Optional second review step: is set if the segment was changed by the repetition editor in the second review step
10REVIEWED_PMPM reviewedPM not assigned to workflowreviewed by a PM not associated in the workflow of a task
11REVIEWED_PM_AUTOPM reviewed, auto-setPM not assigned to workflowreviewed through the repetition editor (auto-propagate of translate5) by a PM not associated in the workflow of a task
12REVIEWED_PM_UNCHANGEDPM reviewed, unchangedPM not assigned to workflowreviewed but unchanged by a PM not associated in the workflow of a task
13REVIEWED_PM_UNCHANGED_AUTOPM reviewed, unchanged, autoPM not assigned to workflowreviewed but unchanged through the repetition editor by a PM not associated in the workflow of a task
  • No labels

2 Comments

  1. It's not clear how the segment endpoint works..

    /editor/segment/[ID]

    Given say, task 500,  with 100 segments, I want to retrieve segment 7 and so call 

    (baseURI)/editor/segment/7

    ...and have the correct token in the header. This returns an error 500 because it knows nothing of the task, but the documentation doesn't make it clear where the task should be referenced (though the error message indicates it should be in the URL).  Can you help?

  2. Hi Stephen,

    Thank you for your feedback regarding the segment endpoint. I have updated the API documentation to clarify its usage.

    The issue you encountered is due to the absence of the taskId in the request URL. To retrieve a specific segment, the taskId must be included in the URL path. Here’s the correct way to format your request:

    (baseURI)/editor/taskid/[taskId]/segment/[segmentId]


    For example, if you want to retrieve segment 7 from task 500, your request URL should be:


    (baseURI)/editor/taskid/500/segment/7


    Please ensure you include the correct token in the header as you have been doing.

    I hope this resolves the issue. If you have any further questions or need additional assistance, feel free to reach out.

    Best regards,

    Aleksandar