Translation Memory API

Translation memories (TMs) store previously translated segments so you can reuse them across projects. When a translator encounters a similar or identical source string, the TM suggests matching translations, improving consistency and reducing effort.

Tip

Translation memories work at the organization level. You can assign multiple TMs to a project with different priorities and configure which one receives new translations automatically.

---

List translation memories

Returns all translation memories in an organization, with pagination.

GET /api/v1/organizations/:orgId/tms

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID

Query parameters

Parameter	Type	Required	Description
cursor	string	No	Pagination cursor from a previous response
limit	integer	No	Items per page (1-100, default: 50)

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/organizations/1/tms

Example response

{
  "tms": [
    {
      "id": 1,
      "organizationId": 1,
      "name": "Main TM",
      "description": "Primary translation memory for all projects",
      "sourceLocaleId": 10,
      "sourceLocaleCode": "en",
      "isDefault": true,
      "isShared": true,
      "autoPopulate": true,
      "onlyApproved": false,
      "entriesCount": 12450,
      "languageCount": 8,
      "linkedProjectsCount": 3,
      "createdAt": "2025-01-10T08:00:00Z",
      "updatedAt": "2025-03-20T14:00:00Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Response fields

Field	Type	Description
id	integer	TM ID
organizationId	integer	Organization this TM belongs to
name	string	TM name
description	string | null	Optional description
sourceLocaleId	integer	Source language locale ID
sourceLocaleCode	string	Source language code (e.g., en)
isDefault	boolean	Whether this is the organization’s default TM
isShared	boolean	Whether this TM is shared across projects
autoPopulate	boolean	Automatically add new translations to this TM
onlyApproved	boolean	Only store reviewed/approved translations
entriesCount	integer	Total number of entries
languageCount	integer	Number of unique target languages
linkedProjectsCount	integer	Number of projects using this TM
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

---

Create translation memory

Create a new translation memory in an organization.

POST /api/v1/organizations/:orgId/tms

Path parameters

Parameter	Type	Required	Description
orgId	integer	Yes	Organization ID

Request body

Field	Type	Required	Description
name	string	Yes	TM name (1-255 characters)
description	string	No	Optional description (up to 2000 characters)
sourceLocaleId	integer	Yes	Source language locale ID
isShared	boolean	No	Share across projects (default: false)
onlyApproved	boolean	No	Only store approved translations (default: false)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing TM",
    "description": "Translation memory for marketing content",
    "sourceLocaleId": 10,
    "isShared": true
  }' \
  https://api.comvi.io/api/v1/organizations/1/tms

Example response

{
  "id": 2,
  "organizationId": 1,
  "name": "Marketing TM",
  "description": "Translation memory for marketing content",
  "sourceLocaleId": 10,
  "sourceLocaleCode": "en",
  "isDefault": false,
  "isShared": true,
  "autoPopulate": false,
  "onlyApproved": false,
  "entriesCount": 0,
  "languageCount": 0,
  "linkedProjectsCount": 0,
  "createdAt": "2025-03-25T12:00:00Z",
  "updatedAt": "2025-03-25T12:00:00Z"
}

---

Get translation memory

Retrieve details of a specific translation memory.

GET /api/v1/tms/:tmId

Path parameters

Parameter	Type	Required	Description
tmId	integer	Yes	Translation memory ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/tms/1

Example response

Returns the same TM object format as the Create translation memory response.

---

Update translation memory

Update a translation memory’s settings.

PATCH /api/v1/tms/:tmId

Path parameters

Parameter	Type	Required	Description
tmId	integer	Yes	Translation memory ID

Request body

Field	Type	Required	Description
name	string	No	Updated name
description	string | null	No	Updated description (set to null to clear)
isShared	boolean	No	Update sharing setting
autoPopulate	boolean	No	Enable/disable automatic population
onlyApproved	boolean	No	Only store approved translations

Example request

curl -X PATCH \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "autoPopulate": true,
    "onlyApproved": true
  }' \
  https://api.comvi.io/api/v1/tms/2

Example response

Returns the updated TM object.

---

Delete translation memory

Permanently delete a translation memory and all of its entries.

DELETE /api/v1/tms/:tmId

Path parameters

Parameter	Type	Required	Description
tmId	integer	Yes	Translation memory ID

Example request

curl -X DELETE \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/tms/2

Response

Returns 204 No Content on success.

Caution

Deleting a TM is irreversible. Export your TM as a TMX file first if you want to keep a backup.

---

Search for matches

Search a translation memory for matches against a source text. Returns results ranked by similarity.

POST /api/v1/tms/:tmId/search

Path parameters

Parameter	Type	Required	Description
tmId	integer	Yes	Translation memory ID

Request body

Field	Type	Required	Description
sourceText	string	Yes	Text to search for (1-10000 characters)
targetLocaleId	integer	Yes	Target language locale ID
contextKey	string	No	Translation key for context-aware matching (up to 512 characters)
minSimilarity	integer	No	Minimum similarity percentage (50-100, default: 75)
maxResults	integer	No	Maximum number of results (1-20, default: 5)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceText": "Welcome to the dashboard",
    "targetLocaleId": 11,
    "minSimilarity": 70,
    "maxResults": 5
  }' \
  https://api.comvi.io/api/v1/tms/1/search

Example response

{
  "matches": [
    {
      "id": 5001,
      "sourceText": "Welcome to the dashboard",
      "targetText": "Bienvenue sur le tableau de bord",
      "targetLocaleId": 11,
      "similarity": 100,
      "matchType": "exact",
      "contextKey": "dashboard.welcome",
      "sourceProjectName": "Web App",
      "authorName": "Jane Smith",
      "tmName": "Main TM",
      "usageCount": 12
    },
    {
      "id": 5002,
      "sourceText": "Welcome to your dashboard",
      "targetText": "Bienvenue sur votre tableau de bord",
      "targetLocaleId": 11,
      "similarity": 92,
      "matchType": "fuzzy",
      "contextKey": null,
      "sourceProjectName": "Mobile App",
      "authorName": "Bob Johnson",
      "tmName": "Main TM",
      "usageCount": 3
    }
  ],
  "total": 2
}

Match types

Type	Similarity	Description
perfect	101	Exact match with identical context key
exact	100	Exact text match (different or no context)
fuzzy	50-99	Partial match based on text similarity

---

Import TMX file

Import translation segments from a TMX (Translation Memory eXchange) file.

POST /api/v1/tms/:tmId/import

Path parameters

Parameter	Type	Required	Description
tmId	integer	Yes	Translation memory ID

Request body

Field	Type	Required	Description
content	string	Yes	TMX file content (XML string, up to 10 MB)
conflictResolution	string	No	How to handle duplicates: skip (default), overwrite, or keep_highest
localeMapping	object	No	Map locale codes in the file to your locale codes (e.g., {"en-US": "en"})

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><!DOCTYPE tmx SYSTEM \"tmx14.dtd\"><tmx version=\"1.4\">...</tmx>",
    "conflictResolution": "overwrite",
    "localeMapping": {"en-US": "en", "fr-FR": "fr"}
  }' \
  https://api.comvi.io/api/v1/tms/1/import

Example response

{
  "imported": 1250,
  "skipped": 30,
  "errors": [
    "Row 45: target locale 'xx' not found"
  ]
}

Response fields

Field	Type	Description
imported	integer	Number of segments successfully imported
skipped	integer	Number of segments skipped (duplicates or invalid)
errors	string[]	List of error messages for failed entries

Note

TMX files are limited to 50,000 translation units per import. Split larger files into smaller batches.

---

Export as TMX

Export the entire translation memory as a TMX file. The response is streamed as XML.

GET /api/v1/tms/:tmId/export

Path parameters

Parameter	Type	Required	Description
tmId	integer	Yes	Translation memory ID

Query parameters

Parameter	Type	Required	Description
targetLocaleId	integer	No	Filter export to a specific target language

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  -o translations.tmx \
  https://api.comvi.io/api/v1/tms/1/export

The response has Content-Type: application/xml and Content-Disposition: attachment; filename="TM Name.tmx".

---

Errors

Status	Error Code	Description
400	INVALID_INPUT	Invalid source locale, target locale, or request body
400	VALIDATION_ERROR	TMX file is invalid or exceeds 50,000 translation units
403	FORBIDDEN	Missing translation memory permission
404	NOT_FOUND	Translation memory not found

---

Next Steps

Translation Memory in the Platform Manage TMs from the dashboard.

Glossaries API Enforce terminology consistency.

Translations API Manage translation keys and values.

Machine Translation API Combine TM with machine translation.