Skip to main content

resources/segments/search

Permits to find segments by a wide range of criteria.

URL

(POST) /api/resources/segments/search

PARAMETERS

The message body contains a JSON object with these properties.

scope

The scope object. It delimits the total range of segments and related resources that can be queried.

Example:

CODE 
"scope": { "type": "Project", "projectid": 1234 }
Mandatory, object
query

The filters to apply. See chapters further down.

Get segments in scope with a word in English and where the German translation has green status. Further, we want the segment context to be a "Heading" (we suppose we translate a Microsoft Word document).

CODE 
"query": {
	"ctx": { "value": "Heading", "mode": "Prefix" },
	"languages": [
    	{ "locs": ["en"], "text": { "value": "ministry" } },
    	{ "locs": ["de"], "status": { 1 } }
	]
}
Optional, object?
layout

Optional layout object. The layout presets the data and the languages you want to retrieve with the results.

If not specified or null the layout is preset - see autoLayout property below.

Optional, object?
autoLayout

If layout is not set, the system creates one depending on the values of this property:

  • "Languages" or null/missing: System returns columns for all languages in the languages node
  • "Default": System fetches a default layout for the scope and the user.
  • Null or missing: The layout is preset for the languages you specify in query.languages, see below:


This example returns results in 3 languages. Not setting the layoutMode requires explicitly specifying languages:

CODE 
{
	"scope": {
		"type": "Job",
		"jobid": 16682,
		"jobcdyt": true
	},
	"query": {
		"languages": [    	
			{ "locs": ["en"] },
    		{ "locs": ["de"] },
			{ "locs": ["fr"] }
		]
	}
}

Alternatively, this can be written more compactly:

CODE 
...
"query": {
	"languages": [
    	{ "locs": ["en", "de", "fr"] }
	]
}
...

Optional,

string




usecache

Optional boolean, default is true.

Set to false only if there is a possibility that user access rights have changed. False enforces the system to recalculate all access rights for the specified scope.


Optional, bool?




Smart navigation - See explanation below


previousSkip

This is the skip value of the currently shown editor page (i.e. before making this call).

Use previousSkip and previousTotal when implementing translation editor interfaces. Here the user may apply a filter and navigate between pages. Consider this scenario: User sets a filter to show green status segments only. User is on page 2. Now user, sets some segments into red status and saves changes. Finally, user clicks button to move to next page (3). With smart navigation, the system will adjust the skip value to maintain it on page 2 (since page 2 now shows new segments).

Optional, int?
previousTotalThis is the grand total amount of segments was obtained when showing the current editor page (i.e. the total known by editor before making this call)Optional, int?



includeRights

Default: false

  • true: Includes full scope/rights details with the results (result.rights)
  • false: Do not include rights with results. Instead the result.rights node will be null.

Use false when possible to reduce http response size.

Optional, bool
includeLayout

Default: false

  • true: Always include the layout for the results.
  • false: Include the layout with the result only if the API method was called without a layout

Use false when possible to reduce http response size.

Optional,

bool

data

User custom data. You can put your own data here. It will be persisted when saving/loading queries for later reuse: resources/segments/search/profiles

Optional,

string


Paginate and sort

To paginate results, use these properties:


query.skip

Optional, default is 0. Used for pagination. Specifies the number of segments in the result set to skip.

Optional, int
query.take

Optional, default is 20. Specifies the number of segments to retrieve.

Setting take to 0 maybe useful if you only want to obtain the grand total for the filter (without fetching segments).

Optional, int
query.sort

Optional. Default is "Natural". Specifies how results shall be sorted:

  • Natural: The recommended value. It applies the Document order with jobs and projects and by date of creation with other scopes.
  • SegmentId: Sort by creation date with most recent on top. The segment id is an auto-incremented unique number. This is the sort option that performs best.
  • Document: Sort by resource, then document, then sequential segment number. Use with job and project scopes only.
  • Text: Sort alphabetically in the first language specified in the languages property.
  • TextLength: Sort by text length, shortest on top, in the first language specified in the languages property.
  • Comments: Sort by comments. This is a special mode that requires the comments property be set. Used when you are basically interested in comments.

Example:

CODE 
"sort": "Natural"
Optional, string
query.sortdir

Optional sort direction. Options are:

  • null / missing: Applies the most natural or logical direction for the selected sort.
  • asc: Ascending
  • desc: Descending

Example:

CODE 
"sortdir": "desc"

Default sort orders:

  • Natural: For job/project scopes uses "asc" (in the order of the document) otherwise "desc" (most recent segments on top)
  • SegmentId: "desc", most recent segments on top
  • Text: "asc", alphabetical order
  • TextLength: "asc", shortest texts on top


Optional, string?
query.highlight

Optional, default is null. 

Instruction whether to highlight texts in the results that actually matched a filter in that language.

Useful with terminology searches where you want to know which of the term variants in a concept actually matched the filter.

Without highlighting, the system will return the concept but does not tell you which of the 3 variants is matching.

Values are:

  • null or "None": No highlighting
  • "FlagTextHits": Add "_ismatch": true with the resulting text or text variant.
Optional, string?


Go to instructions

Use the goto parameter for advanced navigation:

  • Jump to a specific segment id. Query adjusts "skip" accordingly.
  • Jump to the next or previous locked text

Instructions:

  • Make sure to set the take parameter to specify your pagination size
  • Check the gotoSuccess property in the method result. If it is false then the navigation did not find anything.
  • The result.skip and result.take properties are the resulting pagination details.
  • This feature works only with certain sort values, check applicable notes below.


goto

Navigate to segment by segment ID

Specify mode and segment ID as shown below.

CODE 
"goto": {
	"mode": "SegmentId",
	"sid": 2991
}
Optional, object

Navigate to segment by sequential ID

Segments of documents are assigned a sequential ID such as 1, 2, 3-1, 3-2 etc.

The first part is the bee segment ID (bsid), the second part is the sub segment ID (bssid).

CODE 
"goto": {
	"mode": "BeeSegmentId",
	"bsid": 10,
    "bssid": 0
}

The bssid is optional. 0 denotes the first sub segment, 1 the second. In the user interfaces we display this number incremented by 1 (after all "3-1" looks better than "3-0"

NOTE: This mode is available only with Job or Project scopes.




Navigate to locked text

Navigates to the next (next: true) or previous (next:false) locked text relative to the specified segment ID.

CODE 
"goto": {
	"mode": "LockedYes",
	"sid": 88721,
	"locale": "fr",
    "next": "true"
}

The locale parameter is mandatory.




Navigate to non-locked text

Navigates to the very first unlocked segment. Here we drop the sid value and thus navigate from the start.

CODE 
"goto": {
	"mode": "LockedNo",
	"locale": "fr",
    "next": "true"
}

The locale parameter is mandatory.





Filter resources and documents

The scope generally delimits the searchable resources, documents or segments. If the scope is a project then you will get the documents in this project.The following properties permit to drill down on the scope resources, documents or segments.


query.documentSets

Optional list of resources to search. A resource can be a translation memory, a term base or a project memory. See resources/documentsets to find resources and their IDs (dsid).

Example:

CODE 
"documentSets": [ 1292, 19923 ]
Optional, int[]
query.documents

Optional list of documents to search. With projects, a document is, well, a document being translated. With resources it groups segments added to a resource together. See resources/documents/list (post) to find documents and their IDs (did)

Each element is an object with these properties:

  • did: The document ID
  • minbsid, maxbsid: Optional (int?). Defines an optional range of the sequential segment ID in the document. The first segment in a document has number 1.
  • minbssid, maxbssid: Optional (int?). Defines an optional range of the sub-segment numbers starting at 0. If a segment is split into sub-segments, all the sub-segments share the same bsid but have a different bssid.

Example:

CODE 
"documents": [ { "did": 77362 } ]


Optional, object[]
query.segments

Optional list of segments to search. The segment ID is the sid property included with search results.

Example:

CODE 
"segments": [ 992821, 992822 ]


Optional, int[]
query.segmentsFT

Optional string with a list of segment IDs or ID ranges. Examples:

  • 10000, 10002  10003  : Search these 3 segments
  • 100 : 200   300:301  : Search segments 100 to 200 and 300 to 301, inclusive
  • 100:  : Search all segments 100, 101, etc.
  • :100 : Search segments up to 100
Optional, string?
query.segmentNumbers

Optional list of segment numbers to search. The segment number is the bsid property included with search results. It is available with projects and jobs only and is an incremental number starting at 1 (per each document).

The number may contain a subsegment ID:  2-1, 2-2, 2-3  (if segment 2 is split into 3 subsegments).

Optional, string[]
query.segmentNumbersFT

Optional string with a list of segment IDs or ID ranges. Examples:

  • 10, 11  12  : Search these 3 segments
  • 10-3  : Search the 3rd subsegment of segment 10
  • 100 : 200   300:301  : Search segments 100 to 200 and 300 to 301, inclusive
  • 100:  : Search all segments 100, 101, etc.
  • :100 : Search segments up to 100
Optional, string?
query.resourceTypes

Optional filter on the type of resource to search:. Options are:

  • 1: To search documents of a project (aka project memories)
  • 2: To search translation memories
  • 3: To search terminology databases

Example to search resources only while excluding any documents:

CODE 
"resourceTypes": [ 2, 3 ]
Optional, int[]


Filter segment level properties

The scope generally delimits the searchable resources, documents or segments. If the scope is a project then you will get the documents in this project. The following properties permit to drill down on the scope resources, documents or segments.


query.ctx

To filter by the context string of a segment. The context may be the style (such as Heading 1 in a Microsoft Word document) or a software string ID.

This element is an object with the following properties:

Optional, object
query.ctx.valueThe string to search. The search is case-insensitive.Mandatory, string
query.ctx.mode

The search mode, any of these options. If missing then uses the "Prefix" mode.

See String filter (Filter) for details.

Optional, string
query.ctxs

To search segments by one or more context strings. The context may be the style (such as Heading 1 in a Microsoft Word document) or a software string ID.

The search is case-insensitive but otherwise an exact search (not a prefix search).

Optional, string[]



query.constraints

Optional. To find segments that have or have no size constraint (max or min length in translations).

Missing or null: No filter. True: Segment must have a size constraint. False: Segment must not have a size constraint.

Optional, bool



query.cfs

Optional filter for segment-level custom fields.

A array of custom field filters. Each element filters one custom field value:

  • id: The numeric ID of the custom field. Custom fields have IDs starting at 1. Mandatory.
  • val: The value to find. Mandatory
  • mode: The search mode. Uses "Plain" if not specified. Optional (See text.mode)
    Note: The search is an exact search for pick list custom fields, you can choose the mode for other field types.
  • phrase: Optional phrase match flag. Default is false.

Example to find values prefixed with "Department" in custom text field #1:

CODE 
"cfs": [ { "id": 1, "val": "Department.*", mode: "Regex" }, { "id": 5, "val": "Priority", "phrase": true } ]

When specifying multiple items, all of them must match.

Optional, object[]
query.lbls

Optional filter for segment-level labels.

A array of label filters. Each element filters one label value:

  • id: The numeric ID of the label. Labels have IDs starting at 1. Mandatory.
  • val:
    • The numeric label option to find. Use 0 for the first value option, 1 for the second, etc.
    • Use null to find segments where the label is not set. With labels configured to be always visible, a null-query is equivalent to finding the default value of the label. 

Example:

CODE 
"lbls": [ { "id": 1, "val": 0 }, { "id": 23, "val": 3 }, { "id": 10, "val": null } ]

When specifying multiple items, all of them must match.

Optional, object[]
query.tbx

Optional filter on term-level TBX fields. An array of TBX field and value pairs. Each array element has these properties:

  • id: TheTBX field ID. Mandatory.
  • val: The value to find.
  • mode: Optional search mode. Any of "Plain" (default, prefix search), "Wildcards", "Regex" or "Empty"
  • phrase: Optional phrase match flag. Default is false.

Example:

CODE 
"tbx": [ { "id": "context", "val": "Mechanical" }, { "id": "example", "val": "stru*e", "mode": "Wildcards" } ]
Optional, object[]


Language filters

To filter source texts and translations.

query.languages

Optional array of languages and filters to apply. This permits to find source texts or translations by a wide range of filter criteria.

See table below for object properties.

Example: Find all source texts containing word "ministry" and where the German translation if flagged as erroneous.

CODE 
{ 
	"query": {
		"languages": [
    		{ "locs": ["en"], "text": { "value": "ministry" } },
    		{ "locs": ["de"], "status": { "Red" } }
		]
	}
}
Optional, object[]


Each element in languages has these properties:

locs

An array with one or more language codes. With multiple languages, filters apply to either one of the languages (a boolean "OR"). Let us look at an example:

Example 1: Search segments that contain "ministry" in any of the 3 languages:

CODE 
{ 
	"query": {
		"languages": [
    		{ "locs": ["en", "de", "fr"], "text": { "value": "ministry" } }
		]
	}
}


Example 2: Search segments that contain "ministry" in all of the 3 languages:

CODE 
{ 
	"query": {
		"languages": [
    		{ "locs": ["en"], "text": { "value": "ministry" } },
			{ "locs": ["de"], "text": { "value": "ministry" } },
			{ "locs": ["fr"], "text": { "value": "ministry" } }
		]
	}
}


Mandatory, string[]



textOptional filter on the text of the language.Optional, object
text.value

The string to search.

Find any translation containing a word, case insensitive:

CODE 
"text": { "value": "ministry of energy" }

Find all texts starting with:

CODE 
"text": { "value": "Chapter*", "mode": "Wildcards", "case": false, "phrase": true }
Mandatory, string
text.mode

The optional search mode. Uses "Plain" if not specified.

  • Plain: Searches the value. (default)
  • Wildcards: Allows wildcards "*" and "?" in the value.
  • Regex: The value is a regular expression.


Optional, string
text.case

Case sensitive constraint. By default false.

True: Search is case sensitive. False: Search is case insensitive.

Optional, bool
text.phrase

Optional, default is false. If true then the value must match the complete text. If false then the system does an infix search.

With regular expressions or wildcards and phrase set to true: The system automatically prepends and appends * or .*?

Optional, bool



hasText

Optional. Default is null:

  • true: A text must exist
  • false: There must be no text
  • null: No filter


Optional, bool?
hasBadOrMissing

Permits to find erroneous translations:

  • true: Find all translations that are either missing/empty or have a red status
  • false: Find all translated texts and which are not red status
  • null: no filter


Optional, bool?
hasQAError

Filter segments with or without QA error. Optional. Default is null.

True: Segments with QA error. False: Segments without QA error. Any dismissed QA errors are not considered.


Optional, bool?
qaAdvanced filter for QA issues, see Searching - QA issuesOptional, object
status

Filter by status. An optional list of one or more statuses. See Text Status (Enumeration)

  • 0: Neutral status
  • 1: Green status ("OK")
  • 2: Red status ("Problem")


Example:

CODE 
"status": [ 2 ]
Optional, int[]
bookmarks

Filter by bookmark. An optional list of one or more bookmarks. See Text Bookmark (Enumeration)

  • 0: No bookmark set
  • 1: Blue bookmark
  • 2: Red bookmark

Example:

CODE 
"bookmarks": [ 1, 2 ]

Optional, int[]


dttext

Filter on the last text change date. This is an optional object.

See Date filter (Filter) for details.

Examples:

Periods are accumulated. The following finds texts changed the last 3 days:

CODE 
"dttext": { "hours": 48, "days": 1 }

Find changes of October (UTC):

CODE 
"dttext": { "min": "2018-10-1T00:00:00Z", "max": "2018-11-1T00:00:00Z" }
Optional, object
dtflags

Filter on the last status or bookmark change. This is an optional object. The properties are the same as for dttext.

Example for finding any texts changed on or after a date:

CODE 
"dtflags": { "min": "2018-10-26T10:40:00Z" }
Optional, object

lengthMin

lengthMax

Filter on the text length. The following finds all texts between 10 and 20 characters:

CODE 
"lengthMin": 10,
"lengthMax": 20

Find texts with maximum of 10 characters:

CODE 
"lengthMax": 10

Optional, int?

Optional, int?

locked

Filter texts that are explicitly locked or unlocked for editing.

  • True: Only locked texts.
  • False: Only unlocked texts.

Example to find locked texts:

CODE 
"locked": true
Optional, bool?
hasHistory

Filter texts that have a text change history. A text has a history if the first (initial) text, whether typed by a human or coming from a pre-translation, was changed at least once.

Texts with history are generally referred to as post-edited or revised.

True: Only locked texts. False: Only unlocked texts.


Optional, bool?
editors

Filter texts by who is responsible for the latest version. See available options here: Last Editor (Enumeration).

Find all types of pre-translations:

CODE 
"editors": [ 2, 3, 6, 7, 8, 9 ]

Find texts last edited by a human:

CODE 
"editors": [ 1 ]

Optional, INT[]
pastEditors

Filter texts by who has edited a past version of the text. See available options here: Last Editor (Enumeration).

Find any text that was initially a machine translation:

CODE 
"pastEditors": [ 5 ]
Optional, INT[]
users

Filter texts that were last edited by specific users.

CODE 
"users": [ 100, 110 ]
Optional, int[]
repetitions

Permits to find repetitions identified during the last word count (e.g. when marking the file for translation in Codyt). This filter must be set on a target language and NOT the source language. Options are:

  • Identicals: Filter segments that are identical (100% or 110%) repetitions within project
  • NotIdenticals: Filter all segments except those that are identical repetitions within project
  • Any: Filter identical or fuzzy repetitions within project. It depends on the word count configuration whether fuzzy repetitions are identified and down to which similarity threshold.
  • NotAny: Filter all but identical and fuzzy repetitions.


Optional, string?



cfs

Optional filter for language-level custom fields.

A array of custom field filters. Each element filters one custom field value:

  • id: The numeric ID of the custom field. Custom fields have IDs starting at 1. Mandatory.
  • val: The value to find. Mandatory.
    Note: The search is an exact search for pick list custom fields and a prefix search for all other custom field types. Mandatory.
  • mode: Optional search mode. Any of "Plain" (default, prefix search), "Wildcards", "Regex" or "Empty"
  • phrase: Optional phrase match flag. Default is false.

Example to find values prefixed with "Department A" in custom field #1:

CODE 
"cfs": [ { "id": 1, "val": "Department A" }, { "id": 5, "val": "Priority" } ]

When specifying multiple items, all of them must match.


Optional, object[]
lbls

Optional filter for language-level labels.

A array of label filters. Each element filters one label value:

  • id: The numeric ID of the label. Labels have IDs starting at 1. Mandatory.
  • val:
    • The numeric label option to find. Use 0 for the first value option, 1 for the second, etc.
    • Use null to find segments where the label is not set. With labels configured to be always visible, a null-query is equivalent to finding the default value of the label.

Example:

CODE 
"lbls": [ { "id": 1, "val": 0 }, { "id": 23, "val": 3 }, { "id": 10, "val": null } ]

When specifying multiple items, all of them must match.

Optional, object[]
tbx

Optional filter on term-level TBX fields. An array of TBX field and value pairs. Each array element has these properties:

  • id: TheTBX field ID. Mandatory.
  • val: The value to find.
  • mode: Optional search mode. Any of "Plain" (default, prefix search), "Wildcards", "Regex" or "Empty"
  • phrase: Optional phrase match flag. Default is false.

Example:

CODE 
"tbx": [ { "id": "context", "val": "Mechanical" }, { "id": "example", "val": "stru*e", "mode": "Wildcards" } ]
Optional, object[]



dataAny additional string data you want to include for your specific purposes. This is useful if you load/save search profiles resources/segments/search/profiles and you need to persist additional data here.Optional, string?





Comments filters

To filter comments attached to segments.

query.comments

Example to find segments with a comment containing a text:

CODE 
"comments": {
	"locs": [ "fr" ],
	"txt": "grammar"
}


Filter segments that have one or more comments in either English or French or both:

CODE 
"comments": {
	"locs": [ "fr", "en-US" ]
}
Optional, object?
query.comments.locs

An array of the languages to filter. This field is mandatory.

All other properties are optional. Just specifying the languages filters segments that have at least 1 comment attached.

Mandatory, string[]
query.comments.txt

Optional text to find in comments.

This is an infix search and it is case-insensitive

Optional, string?
query.comments.cat

Optional comments category. When adding a comment to a text, the user can choose a category.

Category IDs are numbers 0, 1, 2 in the order they are shown online. The administrator can customize the categories.


Optional, int?
query.comments.uidOptional filter on the person who submitted the comment.Optional, int?
query.comments.dt

Optional filter by comment creation/change date. This object has optional properties:

  • min: Optional earliest inclusive date/time (ISO format).
  • max: Optional latest exclusive date/time. The change date must be before "max".
  • minx: Optional boolean, default is false. If true the minimum value is exclusive (greater than) otherwise inclusive (greater or equal than)
  • maxx: Optional boolean, default is false. If true the maximum value is exclusive (less than) otherwise inclusive (less or equal than)
  • minutes: Optional. Find texts changed since this number of minutes.
  • hours: Optional. Find texts changed since this number of minutes.
  • days: Optional. Find texts changed since this number of days (24 hours * days).

Note: Specify either min/max or minutes/hours/days.


Optional, object?
query.comments.tskOptional filter on the job the submitting user was working on. Task codes are "TR", "RV", etc. and can be customized by the platform administrator.Optional, string?


RESULTS

The message body contains a JSON object:


SEGMENTS
result.rows

The list of segments.

Includes main segment properties as well as the data columns specified in the layout parameter.

The format is explained further down in this page.

object[]
result.totalTotal segments in scope or query. Not dependent on pagination parameters skip and take.int
result.skip

The skip parameter supplied to the method.

When using smart navigation with previousSkip and previousTotal: This value may differ from the skip parameter. See also explanations further up.


result.takeThe take pagination parameter. If you pass no take value to the method, this will be preset to the system default.int




DOCUMENTS AND USERS
result.docs

A dictionary with all documents that appear in the results.

This permits to show document names and more information per segment (see the did property of a segment).

The format is explained further down in this page.

object
result.users

A dictionary with all users/persons that are referenced by the segments included with the results.

A segment references the persons that have last changed a text, a status, a bookmark etc.

The format is explained further down in this page.

object




RIGHTS AND LAYOUT
columnsA JSON array with column details. This enriches the layout object above with a few additional properties (such as if a language is RTL etc).object[]



layout

Optional. Populated if includeLayout parameter is explicitly set to true.

The layout object. The layout passed to the API method or a default layout.

The layout is "cleaned" in that columns not visible to the current user will be removed.

See Spreadsheet Layout (Object) for full details.


object
rights

Optional. Populated if includeRights parameter is explicitly set to true.

The rights object. It provides very granular information on:

  • The user's access rights. There are properties that tell if a user can do certain actions or not.
  • Additional scope details
  • Comments attached on scope level
  • Label properties
  • Custom field properties

See Rights (Object) for full details.

object




GO TO NAVIGATION
gotoSuccess

If you use goto in the request, the API result will include the present property.

  • true: The go to was successful. The result.skip and result.take parameter are the updated pagination details.
  • false: Oups, you tried to navigate to an inexistant segment.


bool?


result.docs

A dictionary with all documents that appear in the results. The keys are the document ids (prefixed with underscore).

See Document Details (Object) for full details.

Example:

CODE 
{
	"_12614": {
		"did": 12614,
		"dsid": 4227,
		"name": "Sample.docx",
		"pmax": null,
		"pmin": null,
		"ptype": 4,
		"pdomain": "MSWORD",
		"edit": true,
		"ctags": ["[b]",
		"[/b]",
		"sub": [{
			"sdid": 1,
			"sdnm": "Word document"
		},
		{
			"sdid": 2,
			"sdnm": "Header"
		}]
	}
}


result.users

A dictionary with all users that are referenced by the segments in the results. The keys are the user ids (prefixed with underscore).

See Persons List (Object) for full details.

Example:

CODE 
{
    "_7": {
      "id": 7,
      "nm": "Stephan",
      "cid": 1,
      "cnm": "Tradubee"
    },
    "_3": {
      "id": 3,
      "nm": "Thierry",
      "cid": 1,
      "cnm": "Freelancebee"
}

Note: Names may be obfuscated if the current user does not have the right to see names.


result.rows

The "rows" property is an array of segments. Each element has these properties.



Identifiers
sidThe unique segment identifier.
no

The sequential segment number. Used with documents and project memories only. Not assigned with translation memories and term bases.

It is composed of the sequential segment number and an optional sub segment number (in case the segment has been segmented).

Numbers for a segment split into three sub-segments: 100, 100-2, 100-3

int
tsLast date/time the segment was updated. The timestamp was introduced in the course of 2018 and therefore the field may be null for older segments.date?
bsidThe sequential segment number. Used with documents and project memories only. Value is 0 for other resource types.int
bssidThe sequential sub-segment number. Assigned if a segment (bsid) was segmented into smaller sub-segments. The number is always sequential starting at 0.int
didThe unique document identifier. A segment is always part of a document. With memories and term bases the document groups segments imported or consolidated together.int
dsidThe unique resource identifier. Each document and segment is part of a resource. Resources can be project memories, translation memories or term bases.int
cty

The resource type:

  • 1: Project memory
  • 2: Translation memory
  • 3: Terminology database
int
sdidThe sub document number. When translation certain file types such as Powerpoint, segments may be further grouped by "sub document". With Powerpoint files, each slide corresponds to a separate sub-document. Null if the segment is not part of any sub-document.int?

Segment level properties
tags

Information on markup in the segment if any. Markup information is encoded as a string using Unicode characters 0x1 and 0x2 as separation codes.


string?
tmx

Array of segment-level TMX or extended properties. Each element has these properties:

  • id: Numeric property id (int)
  • t: The value of the property (string)

The title, description and other details can be obtained here: <reference to be added>.


object[]
edit

Boolean indicating if row properties can be changed or not by the user.

This depends on the type of resource, the user profile, the scope and object we are looking at, business rules and more. For example, a regular user may not change a segment if the scope is for a job and the job has been completed.

bool



ctxThe segment context string. This typically provides contextual information such as "Heading 1", "Table cell" etc.string?
ctx_editIndicates if the context field can be edited by the user.bool
chminOptional minimum character length constraint.int?
chmaxOptional maximum character length constraint.int?
ch_editIndicates if chmin and chmax can be changed by the user.bool
lbls

An array of labels (tags) assigned to the segment. Each item has these properties:

  • id: The numeric identifier of the label
  • value: The numeric label value.
  • sav: A boolean. True if the label is "sticky". Sticky refers to labels that are attached to the segment by default.


The title, description and other details can be obtained here: <reference to be added>.

Note: Only those data are included to which the current user has access.

object[]
lbls_editIndicates if lbls can be changed by the user.bool
cfs

An array of custom fields assigned to the the segment.

Note: Only those data are included to which the current user has access.

object[]
cfs_editIndicates if cfs can be changed by the user.bool




Columns for source text, translations and other information



cols

An object that has one property per column. Columns may exist for source text, translation in one or more languages, text revisions, custom fields and many more columns. If you open the Wordbee translation editor you can define any number of columns and decide which column shall contain which information.

Columns are assigned a sequential number starting at 0 and as per layout. The first column is 0, the next 1 and so on. Column numbers are prefixed by an underscore.

An example of 2 columns:

CODE 
"cols": {
    "_0": { "column": 0,  ***  },
    "_1": { "column": 1,  ***  },
    "_2": { "column": 2,  *** }
}

See table below for column properties.

object[]




Columns - cols array elements

The "cols" property is a dictionary of columns. Each column is of specific type as defined in the layout. The properties included with the results depend on the type.

Each element has these properties:

columnThe sequential column number starting at 0.int
*All properties are column dependent. A column containing a translation will have different properties than a column showing custom fields.


Source/Translation (column type 1)

A column of type source text or translation. See Spreadsheet Layout (Object). This column is associated to a language.

columnThe sequential column number starting at 0.int
txtAn object with all text propertiesstring?
txt.locThe locale of the text (i.e. the language code)string
txt.valThe text valuestring?
txt.stThe status gray (0), green (1) or red (2).int
txt.bkThe bookmark gray (0), blue (1) or red (2).int
txt.tskIf the text was set in the framework of a job then this field contains the task type (TR, RV, PROOF...)string?
txt.cmcThe number of comments attached to this segment.int
txt.edSpecifies who last changed the text. See Last Editor (Enumeration)int
txt.mtidIf a machine translation then this (may) contain the MT profile ID used.int?
txt.usidIf the last editor of the text is a human then this field stores the user's ID.int?
txt.usdtIf the last editor of the text is a human then this field stores the date of the last change.datetime?
txt.hhIndicates if there is a revision history.bool
txt.sim

A value is set by the word count operation if the value is a pre-translation.

The value is 0 by default. Depending on the word count setup, values may be 110, 100 or any value between 50 and 100 (fuzzy pre-translations).

int
txt.rsid

If the segment was pre-translated from a memory hit (typically during the word count) then this field contains the leveraged segment ID.

When the text is edited, the property is reset to null but rsid can be found back in the revision history.

int?
txt.errA QA error informationstring?
txt.lckIndicates if the text is locked for editing.bool
txt.lck_editIndicates if the current user can lock or unlock this text.bool
txt.cfs

An array of custom fields assigned to the this text.

Note: Only those data are included to which the current user has access.

object[]
txt.cfs_editIndicates if cfs can be changed by the user.bool
txt.usfidThe user who last changed either status, bookmark or lock.int?
txt.usfdtThe date when a user last changed either status, bookmark or lock.datetime?

Available with segments from terminology databases only:
txt.var

Optional code for the term variant. In term bases, each text may have multiple variants: plural, singular, synonym... The variant code is optional and user defined.

Context: With term bases a user can add multiple texts (the present record) to each language. NOTE: This feature is available from Q4/2018.

string?
txt.defOptional definition of the term.string?
txt.speechOptional part of speech information for the term.string?
txt.alts

List of alternative terms. This property exists with term base segments only.

Each element is a txt element itself.


txt.sentOptional sentiment analysis score between -10 (negative) and 10 (positive). This value is set manually or using a sentiment analysis system (to be enabled under "Settings" > "Sentiment Analysis". Null means that no score was set.int?
txt.sentdtIf txt.sent is set then this is the date when the score was calculated. If this date is anterior to txt.usdt then the text was changed any (potentially) may require recalculating the score. datetime?


Segment context (column type 2)

The segment context string. This typically provides contextual information such as "Heading 1", "Table cell" etc. This column is associated to the segment and language idenpendent.

columnThe sequential column number starting at 0.int
ctxThe context as a stringstring?
ctx_editIndicates if the user can edit the column.bool



Status (column type 3)

The source text or translation status. This column is associated to a language.

columnThe sequential column number starting at 0.int
st

The status or the source text or translation.

Values are: gray (0), green (1) or red (2).

int
st_editIndicates if the user can edit the column.bool


Last editor (column type 4)

Specifies who last changed the source text or translation. This column is associated to a language.

columnThe sequential column number starting at 0.int
edSpecifies who last changed the text. See Last Editor (Enumeration)int
ed_editIndicates if the user can edit the column.bool


Lock status (column type 5)

Shows if the source text or translation is locked for editing. This column is associated to a language.

columnThe sequential column number starting at 0.int
lckBoolean indicating if text is locked for editing (true).bool
lck_editIndicates if the user can edit the column.bool


Bookmark (column type 6)

The source text or translation bookmark. This column is associated to a language.

columnThe sequential column number starting at 0.int
bkThe bookmark gray (0), blue (1) or red (2).string?
bk_editIndicates if the user can edit the column.bool


Custom field (column type 7)

A segment level or language level custom field value. This column shows the value of one specific custom field (as per layout definition).

columnThe sequential column number starting at 0.int
cfThe context as a string. Null if not set.string?
cf_editIndicates if the user can edit the column.bool


Label (column type 8)

A segment level or language level label with label ID and its numeric value. This column shows the value of one specific label for the segment or a specific language (as per layout definition).

columnThe sequential column number starting at 0.int
lbl

An object with these properties:

  • id: The label's unique ID.
  • value: The label's numeric value.
object
lbl_editIndicates if the user can edit the column.bool


Comments (column type 9)

The comments for a specific language (source text or translation).

columnThe sequential column number starting at 0.int
cms

An array of comments attached to the source text or translation.

See Comment (Object) for properties.

object[]
cms_editIndicates if the user can edit the column.bool


Memory hits (column type 10)

Translation memory hits for the source text or a specific translation.

columnThe sequential column number starting at 0.int
hitsNOT IMPLEMENTED-
hits_editIndicates if the user can edit the column. Always false as memory hits cannot be edited.bool


New comment (column type 11)

A "placeholder" column. In the translation editor we show an editable field to add a new comment to a language upon save.

columnThe sequential column number starting at 0.int
cmnew

Always null.

This column type is for saving new comments to a language. It does not return any information.

string?
cmnew_editTrue if the user can submit a new comment for this segment.bool


Revisions (column type 12)

The revisions in a specific language.

columnThe sequential column number starting at 0.int
revs

An array with the revision history.

See Segment Change (Object) for properties.

object[]
revs_editAlways false.bool


QA errors (column type 13)

A string with QA errors in a specific language.

columnThe sequential column number starting at 0.int
errA string with all QA errors.string?
err_editIndicates if the user can edit the column.bool


TMX/Extended properties (column type 14)

Any additional TMX or extended properties attached to either the segment or a specific language.

columnThe sequential column number starting at 0.int
tmx

Array of segment-level TMX or extended properties. Each element has these properties:

  • id: Numeric property id (int)
  • t: The value of the property (string)

The title, description and other details can be obtained here: <reference to be added>.

string?
tmx_editIndicates if the user can edit the column and add, remove or change properties.bool




EXAMPLE

See resources/segments/search - Examples







JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close