Content Requests

Requesting a localization or creation of new content is done by submitting a content request. Content requests can map to anything, but will usually map against a page or product. A minimal request might look like this:

{
  "language": {
    "source": "sv",
    "target": "no"
  },
  "fields": [
    {
      "id": "title",
      "type": "localizable",
      "data": "string",
      "value": "Produkter"
    },
    {
      "id": "body",
      "type": "localizable",
      "data": "html",
      "value": "<p>Denna text kan innehålla <strong>HTML taggar</strong></p>"
    }
  ]
}

A content request can contain the following:

Name Type Description
id string Unique identifier generated when a content request is submitted. Only readable
type type The type of request, will be standard if not specified. See Versioning for more types.
language.source Locale Language that the source text, field names and hints is in. Required
langauge.target Locale Language that the content should be written in. Required
fields array[Field] One or more fields containing either information or something that should be localized or written. Required
state state State of the request. See section below for details. Only readable
created RFC3339 datetime When the request was submitted. Only readable
completed RFC3339 datetime When the request was marked as completed. Only readable

States

Every content request has a state and will pass through certain states before it is completed.

State Description
pending The request has been received by the API. Pending requests can be deleted or modified.
confirmed Request has been processed by Contentor and will be fulfilled soon. The request can no longer be deleted or modified without contacting Contentor.
completed The request has been completed and the content is ready for use.

Fields

Content request are built up of one or more fields. Fields are used both to request a localization of a text, the creation of a text and to deliver contextual information needed to work with a content request.

A field object contains the following values:

Name Type Description
id string Identifier of the field, use this for retrieval of field data and querying of requests.
name string Human readable name of the field. Optional, id is used if this value is not provided.
type type How this field should be treated, either internal, context or localizable. Required
data data type The type of data this field contains, two types are currently supported: string and html. Required
value dynamic Value of this field. Required
originalValue dynamic Original value of this field. Only readable

Field types

Name Description
internal Used for storing data relevant to the submitter but that does not affect the localization and creation of content.
context Contextual information to help writers with localization and content creation.
localizable Used for fields where the value should be localized into another language.
creatable Used for fields where content should be created based on context and hints

Data types

Name Description
string String of text - no formatting and will not be encoded. JSON data is expected to be a string.
html HTML formatted text, needs to be a valid HTML fragment and will be returned HTML encoded. JSON data is expected to be a string.
html:relaxed Like html but will not use strong validation.

Warning

HTML can be messy and our html type uses strong validation to help us write correct HTML. This means that we will validate against the same rules that the W3C Markup Validation Service uses. In certain cases the markup you want to send us might not validate, in which case you can switch to html:relaxed to avoid the use of strong validation.

Hints

Hints can be placed on fields to help with creating better content for you. There are both soft hints, such as target word count and softer ones such as a maximum length to enforce at datababse limit. Different types of fields can support different types of hints. Hints are specified via an array on the field named hints. Example:

{
  "id": "title",
  "type": "localizable",
  "data": "string",
  "value": "Produkter",
  "hints": [
    {
      "type": "length",
      "max": 400
    }
  ]
}

Length limit

Limit the length of the text in a field.

Type: length Use: Works for localizable and creatable fields.

Argument Description
around Optional length of the text, used as an indicator of a desired length, but the finished text can be shorter than this text.
max Optional maximum length of the returned text. The finished text will never be longer than this.

Word count

Set a target on the number of words a text should have.

Type: word-count Use: Only with field type creatable.

Argument Description
around Number of words that the created text should aim for. Used as an indicator on how many words the text should have, but a returned text is allowed to have less words.

Free text

Ties some free text information to a field, similar to context but scoped to a single field.

Type: free-text Use: Works for localizable and creatable fields.

Argument Description
text The text that should be associated with this field.

Examples of fields

Internal field, that can be queried but is not visible during localization and content creation:

{
    "id": "database-id",
    "type": "internal",
    "data": "string",
    "value": "1457355474317"
}

Context field, can be queried and is shown during localization and content creation:

{
    "id": "product-type",
    "type": "context",
    "data": "string",
    "value": "Coffee Brewer"
}

Localizable field, can be queried and should be localized:

{
    "id": "product-listing-text",
    "type": "localizable",
    "data": "html",
    "value": "Coffee Brewer with integrated timer &amp; automatic shut down."
}

Retrieve a localized field:

{
    "id": "product-listing-text",
    "type": "localizable",
    "data": "html",
    "value": "Kaffebryggare med integrerad timer &amp; automatisk avstängning.",
    "originalValue": "Coffee Brewer with integrated timer &amp; automatic shut down."
}

results matching ""

    No results matching ""