Import segments to resource

This method lets you import segments from a file to a memory or termbase.

It allows to import/merge content into an existing resource or to create a new resource on the fly. Formats supported are: Excel, CSV, TMX, TBX, Align Assist and Trados Bilingual Workbench files.

The functionality is very similar to the import tools available in Wordbee Translator. Pages to create a new memory/termbase from a file, or, to upload a file to an existing resource:

URL

(PUT) resources/import?token={tokenid}&data={data}

PARAMETERS

The parameters are a JSON object included in the request body:

token

The token obtained on connection

Mandatory

data

A JSON object containing all import parameters.

IMPORTANT: Make sure to URL encode this json content before adding to the URL.

Mandatory

"Data" property

The data property is a JSON object with these properties:

filetoken

A reference to the previously uploaded file to import.

Prior to calling the present method you need to upload your file using this method:

Uploading a file

It returns the file token.

Mandatory

resource

This object defines the destination resource.

USE CASE 1

Use this approach if you want the system to add content to an existing resource or create a new one if it does not yet exist. Properties are:

name: Name of the destination resource. If the resource does not yet exist, a new resource with this name will be created.
type: Type of resource, either "TranslationMemory" or "TerminologyDatabase". If the resource already exists, the type must match the destination!
importname: Optional name given to this specific import. All imported segments are grouped with this name. If not specified, then the system assigns the current date as the name.

USE CASE 2

If you want to upload a file to resource with specific ID, then a single property is sufficient to do an import:

id: ID of the destination resource.
importname: Optional name given to this specific import. All imported segments are grouped with this name. If not specified, then the system assigns the current date as the name.

Mandatory

options

A JSON object detailing how content is imported. See below.

See example here: Import segments to resource - Examples

Mandatory

"Options" property

Options vary with the type of file you import.

	ALL FILE TYPES
type	A code for the file type. Any of: TMX - A .tmx file TBX - A .tbx file CSV - A .csv file SpreadSheet - An Excel file .xls, .xlsx AlignAssist - An Align Assist file .ftm The code is case sensitive.	string, Mandatory
skipMono	False (default): Import records even if not translated. True: Import records only if translated.	bool?, Optional
skipIdenticals	If true then either skip (set replaceExisting to false) or merge (set replaceExisting to true) records in the file if they already exist in the resource. The comparison is done in the specified source language. Default is false.	bool?, Optional
replaceExisting	If true then replace records in the resource from the file if they are identical (in the source language). If you set this to true you also need to set "skipIdenticals" to true. Default is false.	bool?, Optional
tagsRemove	Remove any markup in segments in the imported file. Recommended if the markup is too verbose or significantly different from markup typically generated in Wordbee Translator. Even with markup suppressed, Wordbee permits to leverage content - There are various settings with resources to cope with markup differences. Default is false.	bool?, Optional
tagsReplaceChar	If markup is removed then this specifies the character to use as a replacement. If null then markup is simply removed. If a blank " " then markup is replaced by a blank, and so on. Defaut is null.	char?, Optional
updateCFOptions	If you map fields from the file to segment custom fields, then this option instructs the system to refresh picklist options after the update. For example, picklist custom fields let you delimit the allowed values to choose from. You can have the list of options be updated from the data contained in the file. Use with care! Default: false.	bool?, Optional
~~isAligned~~	~~DEPRECATED and now disregarded.~~ If the file contains the result of a text alignment process then set this property to true. This tells the system that the order in which segments are imported is relevant. The system will then also import the context of each segment (text before and after).

	TMX SPECIFIC OPTIONS
locales	A dictionary that lists all the languages that shall be imported from the file, as well as which languages must exist in the TMX for a record to be imported (and not skipped). Example: CODE `"locales": { "en-US": true, "fr-FR": false, "es-ES": false }` The boolean indicates if the language must be present with a file record to be imported. Typically, at minimum, you set the source language to true. Uploading content to existing resources: Please make sure that you configure all the languages you want to import in the target resource. For example, if your resource has English and French and you want to import Russian data then please first add the Russian language in the resource's properties.	object, Mandatory
sourceLocale	The source language code. In the above example this probably is "en-US".	string, Mandatory
~~mergeLocale~~	~~DEPRECATED. The system uses property "sourceLocale" instead. It is the language in which the system looks for existing identicals.~~

	TBX SPECIFIC OPTIONS
locales	A list of all languages that shall be imported from the file. Example: CODE `"locales": [ "en-US", "fr-FR", "es-ES" ]`	object, Mandatory
sourceLocale	The source language code. This language must be part of the locales list.	string, Mandatory
~~mergeLocale~~	~~DEPRECATED. The system uses property "sourceLocale" instead. It is the language in which the system looks for existing identicals.~~
encoding	The encoding of the file. If not specified the system uses "utf-8".	string, Optional
commentsFields	Optional list of TBX properties that shall be imported as comments. The allowed numeric values are: 0 - Notes 1 - Descrip: Provides descriptive information about the node 2 - Admin: Contains information of an administrative nature for the node in question, such as the source of information, or the project or client for which it applies. 3 - Transac: Transactional information. 4 - Contains information about a "transaction" (eg: adding of a term, modification etc). Adds XML notes "transactionType", "responsibility", "date" 5 - TermNote: A meta data-category used for describing terms	int[]?, Optional

	ALIGN ASSIST SPECIFIC OPTIONS
locales	A list of all languages that shall be imported from the file. Example: CODE `"locales": [ "en-US", "fr-FR", "es-ES" ]`	object, Mandatory
sourceLocale	The source language code. This language must be part of the locales list.	string, Mandatory

	EXCEL / OPEN OFFICE SPECIFIC OPTIONS
extension	The file's extension, such as ".xsl", "xslx", ".ods" etc. Only valid Microsoft Excel or Open Office spreadsheet file extensions are permitted.	string, Mandatory
columns	Specifies the columns and their content in the spreadsheet. This property is an array of objects, each having these fields: idx: The index of the column in the spreadsheet, starting at 0 (most left column) type: The type of column, any of these string values: "Locale": Contains text in a language, see locale field below. "Label": Content is mapped to a segment label in Wordbee. The cell text must match an existing segment label title. "Comments": Content is imported as a comment to the segment. "Custom": Content is mapped to a segment custom field in Wordbee. locale: Required if type is "Locale" or "Custom" (if you reference a language specific custom field). issrc: Set to true if the locale above is the source language. Required only if type is "Locale". cfid: The string identifier (such as CustomStr3) of the custom field. Required only if type is "Custom". Example: CODE `"columns": [ { "idx": 0, "type": "Locale", "locale": "en", "issrc": true }, { "idx": 1, "type": "Locale", "locale": "fr", "issrc": false }, { "idx": 2, "type": "Comments", "locale": "fr" }, { "idx": 3, "type": "Custom", "cfid": "CustomStr2", "locale": "fr" } ]`	object[], Mandatory
isHtml	Specifies if content is HTML code. If true then the system interprets the content as HTML and protects any markup. Example text: "Hello <b>world</b>". If isHtml is true then the system will import <b> and </b> as protected markup. If isHtml is false, the text will be imported as is without change. Default: false.	bool, Optional
firstRow	The first row containing content. If the spreadsheet has a header row then set this to 1. Default: 0	int, Optional
sheets	Optionally delimit the sheets to import. If not specified then content from all sheets will be imported. Default: First sheet only. Sheets are referenced by their sequential index: 0 = first sheet, 1 = second sheet...	int[], Optional
preserveTagNames	If isHtml is set to true then you should set this property to true as well. If false then all tags are renamed to T1, T2, etc. Default: false Recommendation: Set value to true if isHtml is true.	bool?, Optional

	CSV SPECIFIC OPTIONS
columns	Specifies the columns and their content in the spreadsheet. This property is an array of objects, each having these fields: idx: The index of the column in the spreadsheet, starting at 0 (most left column) type: The type of column, any of these string values: "Locale": Contains text in a language, see locale field below. "Label": Content is mapped to a segment label in Wordbee. The cell text must match an existing segment label title. "Comments": Content is imported as a comment to the segment. "Custom": Content is mapped to a segment custom field in Wordbee. locale: Required if type is "Locale" or "Custom" (if you reference a language specific custom field). issrc: Set to true if the locale above is the source language. Required only if type is "Locale". cfid: The string identifier (such as CustomStr3) of the custom field. Required only if type is "Custom". Example: CODE `"columns": [ { "idx": 0, "type": "Locale", "locale": "en", "issrc": true }, { "idx": 1, "type": "Locale", "locale": "fr", "issrc": false }, { "idx": 2, "type": "Comments", "locale": "fr" }, { "idx": 3, "type": "Custom", "cfid": "CustomStr2", "locale": "fr" } ]`
isHtml	Specifies if content is HTML code. If true then the system interprets the content as HTML and protects any markup. Example text: "Hello <b>world</b>". If isHtml is true then the system will import <b> and </b> as protected markup. If isHtml is false, the text will be imported as is without change. Default: false.	bool, Optional
hasHeader	Indicates if the first row in the file contains a header (and is thus not to be imported). Default: true	bool, Optional
encoding	The encoding of the file. If not specified the system uses "utf-8". Default: "utf-8"	string, Optional
separator	The column separator character. Default: "," (comma)	char?, Optional

	TWBX SPECIFIC OPTIONS
locales	A dictionary that lists all the languages that shall be imported from the file, as well as which languages must exist in the TWBX file for a record to be imported (and not skipped). Example: CODE `"locales": { "en-US": true, "fr-FR": false, "es-ES": false }` The boolean indicates if the language must be present with a file record to be imported. Typically, at minimum, you set the source language to true.	object, Mandatory

RESULTS

The method executes asynchronously. It returns the id of the asynchronous operation or -1 if the operation has completed immediately:

XML

<int xmlns="http://schemas.microsoft.com/2003/10/Serialization/">2147483647</int>

If the value is >= 0 then your software should poll the status of the operation every 5 seconds. See Asynchronous operations, operation "asyncoperations/{operationid}/status".

Note: Currently this method does not return details on the number of records imported.

EXAMPLES

Examples for the options parameter can be found here: Import segments to resource - Examples

The following is a sample for the "data" parameter:

CODE

{
	"filetoken": "050cdfca05c5488ba0cb1db1b2d4ccd9",
	"resource": {
		"id": 3761
	},
	"options": {
		"type": "TBX",
		"encoding": "utf-8",
		"locales": ["en", "fr"],
		"sourceLocale": "en",
		"commentsFields": [],
		"customFields": { },
		"skipMono": false,
		"skipIdenticals": true,
		"replaceExisting": null,
		"tagsRemove": false,
		"tagsReplaceChar": null,
		"updateCFOptions": false
	}
}