String Management

Add, edit, and remove source strings through the Crowdin MCP tools.

Tool Selection

Pick the tool that matches the operation count:

If you need to perform more than one string operation, always use string_batch_operations — regardless of whether you'd otherwise call the single-item tools sequentially, in parallel, or in a loop. The batch tool is faster, uses less API quota, and is the only correct option for any multi-string work.

`string_batch_operations`

{
  "projectId": 130,
  "updateOption": "keep_translations",
  "operations": [
    { "op": "replace", "path": "/{stringId}/{field}", "value": "..." },
    { "op": "remove",  "path": "/{stringId}" },
    { "op": "add",     "path": "/-", "value": { /* new string */ } }
  ]
}

• Max 50 operations per call. Split larger sets into sequential calls.
• path: /{stringId}/{field} for replace; /{stringId} for remove; /- for add.

Operations

Patchable fields (for `replace`)

`add` value schema

Preserving Translations When Editing `text`

Editing a string's text (or identifier) resets its existing translations by default. The updateOption parameter (also available on edit_string) lets you control this:

updateOption only applies when text or identifier changes; ignored for other fields.

Always set updateOption explicitly when editing text or identifier. Omitting it falls back to the API default, which clears both translations and approvals — that destruction can be silent and irreversible.

Choose the value that matches the user's intent — preservation usually fits typo fixes and minor rewordings; clearing fits substantive meaning changes.

Confirm with the user before any destructive choice:

• keep_translations — translations stay, but approvals are dropped. Tell the user that approval work will be lost and ask before proceeding.
• clear_translations_and_approvals — both translations and approvals are wiped. Confirm explicitly; this destroys translator work.
• keep_translations_and_approvals — no destruction; no confirmation needed.

When the user's intent is ambiguous, ask which option they want before making the call.

When to Fetch Current State First

Fetch existing values only when you need them to compute the new value:

When fetching is needed for several strings in the same file, prefer list_strings with a fileId filter (single call) over a get_string per ID.

Updating `context`: Append vs Replace

By default, append new notes to existing context — translator history is valuable, blindly overwriting it loses information. Fetch the current value, add a newline, and append.

Replace the context outright only when the user explicitly asks ("replace the context", "overwrite", "rewrite"). Explicit intent overrides the default.

Atomicity & Error Handling

string_batch_operations is atomic — if any operation fails (invalid ID, duplicate identifier, schema violation, etc.), the entire batch is rejected and no changes are applied. There is no partial success.

When a batch fails:

1. Read the error to find the offending operation.
2. Fix or drop it, then resubmit the rest.
3. Don't retry the same failing batch unchanged. If the same operation fails twice, stop and surface the problem to the user.

Common Patterns

Add multiple strings to a file

{
  "projectId": 130,
  "operations": [
    { "op": "add", "path": "/-", "value": { "text": "Save",   "identifier": "btn.save",   "context": "Save button in settings",   "fileId": 42 } },
    { "op": "add", "path": "/-", "value": { "text": "Cancel", "identifier": "btn.cancel", "context": "Cancel button in settings", "fileId": 42 } }
  ]
}

Append to context for multiple strings

After reading the current values:

{
  "projectId": 130,
  "operations": [
    { "op": "replace", "path": "/1001/context", "value": "Existing note\nNew: shown in settings header" },
    { "op": "replace", "path": "/1002/context", "value": "Existing note\nNew: tooltip on hover" }
  ]
}

Reword text while keeping translations

{
  "projectId": 130,
  "updateOption": "keep_translations",
  "operations": [
    { "op": "replace", "path": "/1001/text", "value": "Save changes" },
    { "op": "replace", "path": "/1002/text", "value": "Discard changes" }
  ]
}

Remove multiple strings

{
  "projectId": 130,
  "operations": [
    { "op": "remove", "path": "/1001" },
    { "op": "remove", "path": "/1002" },
    { "op": "remove", "path": "/1003" }
  ]
}

Set max length / hide / assign labels

{
  "projectId": 130,
  "operations": [
    { "op": "replace", "path": "/1001/maxLength", "value": 30 },
    { "op": "replace", "path": "/1002/maxLength", "value": 0 },
    { "op": "replace", "path": "/1003/isHidden",  "value": true },
    { "op": "replace", "path": "/1004/labelIds",  "value": [5, 12] }
  ]
}

Mixed operations in one call

{
  "projectId": 130,
  "operations": [
    { "op": "add",     "path": "/-",            "value": { "text": "New feature", "identifier": "feature.new", "fileId": 42 } },
    { "op": "replace", "path": "/1001/context", "value": "Updated context" },
    { "op": "remove",  "path": "/1005" }
  ]
}

Reporting Results

After execution, summarize what changed: counts and IDs of strings added, edited, removed. On failure, report the offending operation plus the error so the user can decide how to proceed.