Copy resource content

This method permits to copy the contents of memories or term bases to another resource. Typical use cases are:

Consolidate a project (memory) to a master memory
Copy one resource to another, either to create a clone or to merge translations of resources
Align translations of multiple bilingual memories into one aligned multi-lingual memory

URL

(POST) /api/resources/segments/copy

PARAMETERS

The message body contains a JSON object.

COPY MODE

mode

Specifies how source data is added or merged into the target resource. Set one of these options:

If not specified, the system uses mode "Append".

Append

Simply adds all segments of the source to the target. The system does not compare any texts, does not attempt to skip doubles or merge translations.

This is the simplest and fastest mechanism.

Complement

Use this mode to always keep any translations in the source and in the target, while trying to combine source and target where possible.

This method disregards / skips any source content that already exists in the target resource. In addition, it merges a source segment with a target segment if the languages complement each other.

For example: If you copy French translations into a resource that has Spanish translations only, the system will append a French translation to an existing segment. In other words, the source and target segments are aligned. In no case, will this method replace an existing translation.

It is the text in the src language that is used to map a source segment with a target segment. The text in the src language must be identical for this to happen.

MergeTargetPrimes

Use this operation if translations in the target resource shall never be replaced. And disregard translations in the source if a translation already exists in the target.

This method goes a step further. Based on identical src texts, the system merges source and target segment. If a translation into one language differs from the translation in the target resource, then the target translation is NOT replaced. Instead the system throws away the target text from the source.

MergeSourcePrimes

Use this operation if translations in the target resource shall always be replaced with translations in the source. Again, it is the text in src language that permits to find a target segment to be merged with a source segment.

This method goes a step further. Based on identical src texts, the system merges source and target segment. If a translation into one language differs from the translation in the target resource, then the source translation always replaces the target translation.

Optional, string

THE DATA TO COPY FROM

scope

The scope object specifies the resource or data to copy. Examples:

To copy / consolidate a resource:

{ "type": "DocumentSet", "dsid": 157 }

To copy / consolidate a project:

{ "type": "Project", "projectid": 7726 }

See all available scopes here.

Mandatory

object

src

The source locale or pivot locale. When copying segments, the system compare the texts in this language with the texts in the target resource.

If not specified, the system selects the first language in locales.

It is highly recommended to explicitly specify this property.

Optional, string

locales

The codes of all the languages to copy from the source to the target resource. If not specified, the system will copy ALL the locales of the resources.

"locales": [ "de-DE", "de-AT", "fr-FR" ]

Optional, string[]

query

An optional filter to apply to the exported data. Sample use cases are:

Exclude any translations in red status
Export translations with certain custom fields only
etc.

The query properties and features are described here. Example of exporting texts in neutral (0) or green (1) status thus excluding red status (2):

"query": {
    "languages": [
       { "loc": ["en", "de", "fr"], "status": { 0, 1 }, "hastext": true }
    ]
}

Optional,

object

minimumTexts

Optional number of languages a segment must have at a minimum to be exported. By default this is 2.

1: Includes monolingual (untranslated) segments
2: The segment must have at least 2 language versions (source and 1 translation)
...

Optional, int

skipTargetIsSource

Optional, default is false. If true then translations are not copied if identical to the source text.

Optional, bool

excludeCommentTypes

Optional. List of numeric comments categories. If set then only comments of these categories are included with the copy.

Categories are sequentially numbered and start at 0.

Optional, int[]

markupRemove Optional, default is false. If true then markup is removed from texts. See also property below. Optional, bool

markupReplaceChar

Optional, default is null. When you set markupRemove to true then any markup will be replaced by this character.

Note: You must specify a single character such as: "markupReplaceChar": " "

Optional, char

localesMappings

Use if the language codes in the source and target are not identical. Think of "en" versus "en-US" etc.

Optional dictionary to transform or modify language codes prior to copying. The following example, transforms fully qualified locales from the resource into simpler ones:

"localesMappings": {
"de-DE": "de",
"fr-FR": "fr"
}

Locales not in the dictionary are left unchanged. If you map multiple original locales to the same output locale, the system will retain only one of the "clashing" languages.

Optional, object

THE TARGET RESOURCE

You can either specify an existing translation memory or terminology database, or have the system create a new blank resource as part of the copy.

targetResourceId

The document set id (dsid) of the target resource.

If specified: It must be an existing translation memory or terminology databases. Note that you cannot copy data to a project memory.
If null or not specified: The system automatically creates a new resource with the languages specified in locales and localesMappings.

Optional, int?

targetResourceName

Required if targetResourceId is null. This is the name given to the newly created target resource.

Optional, int?

targetContentType

Required if targetResourceId is null. This is the type of the target resource, any of these 2 values:

2: Translation memory
3: Terminology database

targetDocumentId

Optional. If not set, all copied data will be grouped together into a new "document" within the target resource.

Alternatively, you can specify an existing "document" aka group in the target resource.

Optional, int?

targetDocumentName

Optionally set if targetDocumentId is null. This is the name given to the group or document.

If not specified, the system will assign a name automatically.

Optional, string?

RESULTS

This API method is an "asynchronous" operation. It either immediately returns the result or instead an operation ID which you need to periodically poll until the operation has finished.

Upon the first call you typically get an "operationid". Use this to further poll the operation status. See full explanation here: Asynchronous operation

When the operation is finished you get the reference to the file:

{
    "trm": {
        "status": "Finished"
		...
    },
    "custom": {
        "segmentsSource": 123,
		"segmentsTarget": 60,
		"segmentsAdded": 52,
		"segmentsUpdated": 8
    }
}

When the operation is complete, the method returns the custom node:

segmentsSource: Total segments extracted and filtered from the source resource
segmentsTarget: Total segments added or updated in the target resource. This equals segmentsAdded + segmentsUpdated
segmentsAdded: Total segments added as new records in the target resource
segmentsUpdated: Total segments merged with existing target resource segments.

TIPS

It is generally recommended to set the query parameter, at minimum to select only translated segments.

A very common case is the following: We copy a resource with source language being English and the two target languages German and French. We filter to only copy segments if the source language and at least one translation is present (hastext). As for the target languages we only want to select segments if there is a translation and if the translation does not have the red status (0 = no status, 1 = green status, 2 = red status). The query below will thus skip any segments that have neither a German nor a French translation.

"query": {
    "languages": [
       { "locs": ["en"], "hastext": true },
       { "locs": ["de", "fr"], "status": [ 0, 1 ], "hastext": true }
    ]
 },

EXAMPLES

Consolidate a project into a master memory:

(POST) /api/resources/segments/copy


BODY:
{
 "mode": "Complement",
 "scope": {"type": "Project", "projectid":2202 },
 "locales": ["en", "de", "fr"],
 "src": "en",
 "query": {
    "languages": [
       { "locs": ["en"], "hastext": true },
       { "locs": ["de", "fr"], "status": [ 0, 1 ], "hastext": true }
    ]
 }, 
 "targetResourceId": 2397
}