Source Configuration – Livewords Flow Support

This documentation describes how to configure the API channels or Feed Sources for import and export. The configuration is a Json Map with a set number of key/value pairs. The configuration consists of the following parts.

Some definitions for readers who are not familiar with XML.

Element

An element is a building block of XML. Elements can hold text, elements and attributes.

<element>....</element>

Attribute

An element can have multiple unique attributes. Usually the attributes contain more information about the element. Attributes are key/value pairs. In the example below, the key is the attribute name and the value is the attribute value.

<element key="value">....</element>

General

clientType

Describes the type of client system this configuration is for.

Format

List []

Allowed values

default, demandware

namespaces

XML namespaces are used for providing uniquely named elements and attributes in an XML document. So for example a <title> element is not the same as a <content:title> element. Where content is the namespace addition. When an item is sent to LivewordsFlow or a Feed is extracted, the content is parsed. During this process the namespace needs to be given to parse the document correctly.

Format

Map {}

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items xmlns:excerpt="http://wordpress.org/export/1.2/excerpt/"
      xmlns:posts="http://purl.org/rss/1.0/modules/posts/">
  <item id="12345" title="Title of the item">
    <excerpt:content>The item has a title, an id and content.</excerpt:content>
    <posts:content>
      <![CDATA[The item has a title, an <strong>id</strong> and content.]]>
    </posts:content>
  </item>
</items>

Configuration example

"namespaces" : {
  "excerpt":"http://wordpress.org/export/1.2/excerpt/",
  "posts":"http://purl.org/rss/1.0/modules/posts/"
}

Common mistakes

- The use of = instead of : in the configuration
- A missing comma between namespaces

Define items

The following key/value pairs in the configuration are to define an item and how the item will be displayed. For more information on items refer to the item documentation.

itemLocations

The itemLocation is to define the path to the item in the given XML structure. Here below an example xml with the configuration to define items. It is possible to define multiple items in one XML.

Format

List []

XML example

<?xml version="1.0" encoding="UTF-8"?>
<channel>
  <products>
    <product id="12345" title="Title of the item">
      <content>The item has a title, an id and content.</content>
      <content2><![CDATA[The item has a title, an <strong>id</strong> and content.]]></content2>
    </product>
  </products>
  <pages>
    <page id="67890" url="https://livewords.com/over-ons/>
      <title>About Us</title>
      <description></description>
      <meta-info>
        <keywords>software, translation, cloud</keywords>
        <meta-description>
          We are an Amsterdam-based software company devoted to
          getting the pain out of the traditional localization process.
        </meta-description>
      </meta-info>
    </page>
  </pages>
</channel>

Configuration example

"itemLocations" : [
  "/products/product",
  "/pages/page"
]

Common mistakes

- Not the entire path to the item is given, e.g. "/product"
- The pattern style is used, e.g. "/products/product/**". An item must always be defined literally
- The capital usage is incorrect. So the XML contains capitals but the configuration doesn't
- Forgetting the initial /. Ex of a wrong path. "products/product"

titleExpression

In the To Do list for each item a title and location is displayed. The titleExpression configures the element or attribute that will define the title. The title and location values can be searched through. The title is usually a descriptive text to identify the item. For the title you can assign the value of an attribute as well as the text within an element.

Screen_Shot_2017-11-06_at_15.47.28.png

Format

Map {}

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <title>Title of the item</title>
    <content>The item has a title, an id and content.</content>
    <content2>
      <![CDATA[This text contains <strong>bolder</strong> text
     and <img src="/images/image/one.png" /> image.]]>
   </content2>
  </item>
</items>

Configuration examples

"titleExpression" : {"/items/item" : "feedItemElement.getAttributeValue('title')"}

results in Title of the item

"titleExpression" : {"/items/item" : "titleElement.getAttributeValue('title')"}

results in Title of the item

"titleExpression" : {"/items/item/title" : "titleElement.getText()"}

results in Title of the item

"titleExpression" :
{
  "/items/item" : "feedItemElement.getAttributeValue('id') + ' - ' +
          feedItemElement.getAttributeValue('title')"
}

results in 12345 - Title of the item

Common mistakes

- feedItemElement is used where titleElement should be used

locationExpression

In the To Do list a location is displayed for each item. The location must be assigned attribute value of an item. This is unlike the Title of an item. Users can search through the title and location values from the To Do list.

The title is usually a descriptive text to identify the item. The location has to be a unique value. So it has to be defined with the id of the item.

Format

Map {}

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <title>Title of the item</title>
    <content>The item has a title, an id and content.</content>
    <content2>
      <![CDATA[This text contains <strong>bolder</strong> text
      and <img src="/images/image/one.png" /> image.]]>
    </content2>
  </item>
</items>

Configuration example

"locationExpression" : {
  "/items/item" : "feedItemElement.getAttributeValue('id')"
  }

results in /items/item/12345

Common mistakes

- The location of an item is not always unique. This causes items to override each other.

imageExpression

Images can be shown in the To Do list on an item level. When opening an item for translation, an image button is available. The imageExpression setting is to define the images shown.

Format

Map {}

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <title>Title of the item</title>
    <content>The item has a title, an id and content.</content>
    <images>
      <image>/img/sweater.jpg</image>
      <image>/img/sweater-board.jpg</image>
    </images>
  </item>
</items>

Configuration example

"imageExpression" :
{
  "/items/item/images/image" : "'http://www.livewords.com' + imageElement.getText()"
}

Result in To Do list

http://www.livewords.com/img/sweater.jpg
http://www.livewords.com/img/sweater-board.jpg

Common mistakes

- When the image url is constructed of a fixed value and a value from the XML, it is
important to remember the quotes around the fixed value. For ex,
"http://www.livewords.com + imageElement.getText()" is not valid.

labelExpression

Labels can be added on an item level. The label will be shown in the To Do list as a filter.

If the same item is sent with changed labels, new labels will be merged into existing ones.

It is impossible to remove old labels via API but is possible in the user interface.

Screen_Shot_2017-11-06_at_15.57.37__2_.png

Format

Map {}

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <title>Title of the item</title>
    <content>The item has a title, an id and content.</content>
    <labels>
      <label>AW2017</label>
      <label>HIGH PRIORITY<label>
    </labels>
  </item>
</items>

Configuration example

  "labelExpression" : 
{
 "/items/item/labels/label" : "getText()"
 },

Define translate-able content

includeLocations

This setting defines the paths to the elements that need to be translated.

Format

List []

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <content>The item has a title, an id and content.</content>
    <content2><![CDATA[This text contains <strong>bolder</strong> text and <img src="/images/image/one.png" /> image.]]></content2>
  </item>
</items>

Configuration examples

"includeLocations" : ["/items/item/**"]

"includeLocations" : ["/items/item/content", "/items/item/content2"]

"includeLocations" : ["/items/item/content2"]

ignoreLocations

This setting defines the paths of the elements that do not need to be translated. This can be used when the configuration is created based on Exclusion instead of inclusion. The paths always have to be explicit.

Nodes which contain only a number will be ignored by default.

Format

List []

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <content>The item has a title, an id and content.</content>
    <content2>
      <![CDATA[This text contains <strong>bolder</strong> text
      and <img src="/images/image/one.png" /> image.]]>
    </content2>
  </item>
</items>

Configuration examples

"ignoreLocations" : ["/items/item/content", "/items/item/content2"]

"ignoreLocations" : ["/items/item/content2"]

excludeLocations [deprecated]

This setting defines the paths of the elements that do not need to be translated. These elements will be removed from the translated item xml. This can be used when the configuration is created based on Exclusion instead of inclusion. The paths always have to be explicit.

Format

List []

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <content>The item has a title, an id and content.</content>
    <content2>
      <![CDATA[This text contains <strong>bolder</strong> text
      and <img src="/images/image/one.png" /> image.]]>
    </content2>
  </item>
</items>

Configuration examples

"excludeLocations" : ["/items/item/content", "/items/item/content2"]

"excludeLocations" : ["/items/item/content2"]

Define the content type

cdataLocations

If an XML contains CDATA elements these need to be specified. If you do not specify the CDATA elements the import will still work, however the translated XML will not contain the CDATA elements which will potentially create invalid XML.

Format

List []

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <content>The item has a title, an id and content.</content>
    <content2>
      <![CDATA[This text contains <strong>bolder</strong> text
      and <img src="/images/image/one.png" /> image.]]>
    </content2>
    <content3>
      <![CDATA[This text contains even more <strong>bolder</strong> text
      and no image.]]>
    </content3>

  </item>
</items>

Configuration example

"cdataLocations" : [ "/items/item/content2", "/items/item/content3"]

textLocationTypes

Default value is:

"textLocationTypes" : { "ALL": "text/html" }

All text will be considered as html. It is the easiest way to configure your source. In this case you don't have to reconfigure it. "Simple Preview" of item works only if you have this default configuration.

If nothing is set, the content is assumed to be plain text and will be handled as such. If the content contains html this can be specified here.

Format

Map {}

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <content>The item has a title, an id and content.</content>
    <content2>
      <![CDATA[This text contains <strong>bolder</strong> text
      and <img src="/images/image/one.png" /> image.]]>
    </content2>
  </item>
</items>

Configuration example

"textLocationTypes" :
{
  "/items/item/content2": "text/html"
}

splittingInlineHtmlTags

True will split text within LivewordsFlow when an inline tag is encountered. We strongly recomend set it to false.

Screen_Shot_2017-11-06_at_16.15.11.png

Format

Boolean

Allowed values

true, false

Here below two examples and their representation in the To Do of LivewordsFlow when the setting is true or false.

XML example

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <content>The item has a title, an id and content.</content>
    <content2>
      <![CDATA[This text contains <strong>bolder</strong> text
      and <img src="/images/image/one.png" /> image.]]>
    </content2>
  </item>
</items>

Configuration

"splittingInlineHtmlTags" : true

Result in To Do list

Text: The item has a title, an id and content.
Text: This text contains
Text: bolder
Text: text and
Text: image.

Configuration

"splittingInlineHtmlTags" : false

Result in To Do list

Text: The item has a title, an id and content.
Text: This text contains {strong}bolder{/strong} text and {img} image.

XML example 2

<?xml version="1.0" encoding="UTF-8"?>
<items>
  <item id="12345" title="Title of the item">
    <content>The item has a title, an id and content.</content>
    <content2>
      <![CDATA[The content contains the following: <ul><li>A title</li><li>A
      piece of content</li><li>Another piece of content</li></ul>]]>
    </content2>
  </item>
</items>

Configuration

"splittingInlineHtmlTags" : true

Result in to do list

Text: The item has a title, an id and content.
Text: The content contains the following:
Text: A title
Text: A piece of content
Text: Another piece of content

Configuration

"splittingInlineHtmlTags" : false

Result in to do list

Text: The item has a title, an id and content.
Text: The content contains the following:
Text: A title
Text: A piece of content
Text: Another piece of content

splittingInlineHtmlTagsToIgnore

This option contains a list of inline html tags which will not be split upon splitting. It only works if splittingInlineHtmlTags is set to true. Tag names should be all in lowercase and contain no additional characters.

Configuration example:

"splittingInlineHtmlTags" : true
"splittingInlineHtmlTagsToIgnore" : ["b", "strong"]

Tags added to this list will be treated as if the option splittingInlineHtmlTags was turned to false for them. For examples refer to the splittingInlineHtmlTags option.

WARNING: Adding tags, such as img, to the list will make the translation of their attributes impossible, as the tag will be displayed as a placeholder in the original text.

Format:

List []

Allowed values:

bdi,keygen,mark,meter,output,progress,rp,rt,ruby,time,wbr,tt,i,b,u,s,strike,big,small,em,strong,dfn,code,samp,kbd,var,cite,abbr,acronym,a,img,applet,object,font,basefont,br,script,map,q,sub,sup,span,bdo,iframe,input,select,textarea,label,button,ins,del

Automatic Machine Translation

useComputerTranslations

Set this to true if you want to auto-translate all untranslated texts with Machine Translations on extraction/import of the item.

Format

Boolean

Allowed values

true, false

publishComputerTranslations

Set this to true if you want to auto-publish the text that was automatically Machine Translated. This setting only works when useComputerTranslations=true.

Format

Boolean

Allowed values

true, false

Define when to return items

writeEmptyItems

This setting defines if items that do not contain any content will be sent back in the result.

Format

Boolean

Allowed values

true, false

writeIncompleteItems

This setting defines if items will be sent back when they are not entirely translated.

Format

Boolean

Allowed values

true, false

writeUntranslatedElements

If set to true, elements that do not contain translated text will be sent back. This only applies if writeIncompleteItems=true.

Format

Boolean

Allowed values

true, false

Common mistakes

Invalid Json

Make sure all the separators are typed in correctly and lists and maps are closed properly. You can also validate your Json online (https://jsonformatter.curiousconcept.com/).
A Map always consists of zero or more key/value pairs. Make sure the keys and values are enclosed in double quotes and the pairs are comma separated.

{"key1" : "value1", "key2" : "value2",...,"keyN" : "valueN"}

A List always consists of zero or more values in the following way. Make sure the values are enclosed in double quotes and comma separated.

["value1", "value2",...,"valueN"]

General

clientType

namespaces

Define items

itemLocations

titleExpression

locationExpression

imageExpression

labelExpression

Define translate-able content

includeLocations

ignoreLocations

excludeLocations [deprecated]

Define the content type

cdataLocations

textLocationTypes

splittingInlineHtmlTags

splittingInlineHtmlTagsToIgnore

Automatic Machine Translation

useComputerTranslations

publishComputerTranslations

Define when to return items

writeEmptyItems

writeIncompleteItems

writeUntranslatedElements

Common mistakes

Invalid Json

Comments