Skip to content

API V1

Context Images

Endpoints for the operations that can be performed on the context images

A context image is a screenshot that shows translators where a text appears. Listing needs the contextImagesView permission on the project; creating and deleting need contextImagesManage.

Connection types

When you create a context image, connectType decides how LingoHub connects it to texts:

Type Meaning
KEY_BASED You name the texts by file path and key.
TEXT_BASED You give the exact text; LingoHub connects the texts that match it.
IMAGE_BASED LingoHub detects the text on the image (OCR) and connects the texts it finds.

List context images

The list is paginated: page is the zero-based page index, size the page size, and sort takes property,(asc|desc). The response holds the images in content, next to pageNumber, pageSize, totalPages and totalElements.

Filter the list with urlFilter, a JSON filter that you send URL-encoded. This filter returns the images that aren’t connected to any text:

{"where":{"_and":[{"contextImage[segments]":{"_npresent":true}}]}}

Create a context image

Send a multipart/form-data request with two parts: file, the image, and request, a JSON document with the content type application/json.

curl -X POST "https://api.lingohub.com/v1/$WORKSPACE_URL/projects/$PROJECT_URL/contextImages" \
  -H "Authorization: Bearer $LINGOHUB_API_KEY" \
  -F "file=@screenshot.png" \
  -F 'request={"connectType":"IMAGE_BASED","languageCode":"en","autoConnectSuggestions":false};type=application/json'

Rules for request:

  • connectType and languageCode are required. languageCode is the language of the text on the image.
  • segments must have at least one entry for KEY_BASED and TEXT_BASED. Every entry needs filePathAndKey for KEY_BASED and text for TEXT_BASED. For IMAGE_BASED, omit segments.
  • highlightBox marks where the text appears on the image: left, top, width and height in pixels, measured from the top-left corner.
  • autoConnectSuggestions matters only for IMAGE_BASED: true connects the detected texts at once, false stores them as suggestions for review.
  • description is optional.
{
  "connectType": "KEY_BASED",
  "autoConnectSuggestions": false,
  "description": "Screenshot of the edit screen",
  "languageCode": "en",
  "segments": [
    {
      "filePathAndKey": { "filePath": "strings.xml", "key": "action_edit" },
      "text": "Edit",
      "highlightBox": { "left": 500, "top": 500, "width": 100, "height": 100 }
    }
  ]
}

The response is 200 with the new context image. LingoHub connects the texts after the request, so both counts are 0 in this response; read the list later for the result.

Response fields

Field Meaning
id ID of the context image, for example ci_18USq6822XIv-19847171. Use it to delete the image.
name File name of the uploaded image.
imageUrl URL of the image.
languageCode Language of the text on the image.
connectedSegmentLanguagesCount Number of texts connected to the image.
segmentLanguagesSuggestionsCount Number of suggested connections that wait for review.
source Where the image came from: WEB, API, FIGMA or SDK.
uploadStatus PROCESSING, DONE or ERROR.
textDetectionStatus Status of the text detection: SCHEDULED, PROCESSING, DONE or ERROR.

Delete a context image

The operation deletes the image and its connections and answers 200 with an empty body.

Errors

Status Meaning
400 The request is malformed, for example a missing part or an invalid ID.
401 The API key is missing or invalid.
403 The key lacks the permission the operation needs.
404 The workspace, the project or the context image doesn’t exist.
422 request is invalid, for example segments is missing for KEY_BASED.

Operations

Operation Request
List context images GET /v1/{workspaceUrl}/projects/{projectUrl}/contextImages
Create context image POST /v1/{workspaceUrl}/projects/{projectUrl}/contextImages
Delete context image DELETE /v1/{workspaceUrl}/projects/{projectUrl}/contextImages/{id}