Segments and locks

Read a project's segments with their translation status and lock state, lock or unlock them, and read or add the comments on them, as in the editor.

List segments

List Project Segments returns the segments of a project, one page at a time, in file order.

workUnitUuid and stepLevel can be combined. The answer gives the segments in content, with totalElements and totalPages to page through the rest.

Some older projects return an empty page: their segments are not available through this endpoint.

What a segment tells you

Locked segments

A locked segment cannot be changed in the editor, and an import skips it without an error. Segments are locked by a person in the editor, or automatically by the project's settings (for example for exact translation memory matches). Locking a segment in the editor also confirms it.

Each workflow step has its own copy of the file's segments, so a segment can be locked at one step and not at another: read the work unit you are going to change.

In the bilingual XLIFF file, every <trans-unit> has bwx:locked and bwx:confirmed (yes or no), and a locked one also has translate="no". By default an import never changes a locked segment, whatever the file says. Import with applyStatusFromFile to lock, unlock, confirm and unconfirm segments from those attributes; see Bilingual file round trip.

Lock and unlock segments

Lock or Unlock Segments locks or unlocks segments of one work unit, as the editor's lock button does:

{
  "segmentIds": ["<segment id>", "<segment id>"],
  "locked": true
}

• Up to 1,000 segments per call, all of the work unit in the path. The answer is 204.
• Locking a segment also confirms it; unlocking it also unconfirms it.
• The call changes every segment in it or none. If a segment cannot take the change (it has no target, is over its hard character limit, or is already confirmed or locked in the next workflow step), the answer is 422 with the reasons, and nothing changes. A segment already locked, or already unlocked, is left as it is, so a call can be retried.
• Only the segments in the call change. Unlike the editor, the call does not carry a translation to the segment's repetitions.
• The caller needs the Lock Segments permission on the work unit, and the work unit must be open for changes: for example not cancelled, and with its previous workflow step closed.

Comments

Segments have the same comments as the editor's comments panel. A comment belongs to the segment's position in the file (fileIndex), so every workflow step of the file shares it.

• List Work Unit Comments returns the comments of a work unit's segments, oldest first, a page at a time (page, and size up to 200). Each comment has its id, the segmentId of this work unit's segment, fileIndex, author, text and createdAt; a reply has the parentId of the comment it answers. Other users' private comments are not included.
• Create Segment Comment adds a comment to a segment, {"text": "..."}, or a reply with parentId. Users mentioned in the text as [@First Last:<user uuid>] are notified. The answer is the comment.

In the bilingual XLIFF file, a segment's comments are <note> elements of its <trans-unit>, with their author (from) and creation time in UTC (bwx:date). An import with applyStatusFromFile adds the notes a segment does not have yet as comments; without it, notes are ignored.