LingoHub MCP by usefulapi

List every Lingohub project this API key can see (owned and shared, across workspaces). Each entry has the title, its links and the workspace_url + project_url slugs that every other tool needs. GET /v1/projects.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One project: title, description, owner email, configured locales (project_locales), timestamps and links. GET /v1/{workspace_url}/projects/{project_url}.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    }
  },
  "required": [
    "workspace_url",
    "project_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Translation status of one project: each resource file with per-locale segment counts (NOT_TRANSLATED, DRAFT, TRANSLATED, APPROVED, ...), failing quality checks, the export formats it supports and whether a Git repository is connected and can be pushed to. GET .../projects/{project_url}/status.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "branch": {
      "description": "Project branch name. Default: the project's default branch. An unknown branch is HTTP 422.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "workspace_url",
    "project_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Translation progress of every project in one workspace: title, app URL, total segment count and per-locale counts by status (NOT_TRANSLATED, DRAFT, TRANSLATED, PREFILLED, APPROVED). GET /v1/{workspace_url}/projects/status.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    }
  },
  "required": [
    "workspace_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a new localization project in a workspace (needs settings-management permission on the key). Returns the new project with its links. It adds a project and changes nothing existing; repeating the call can create a second project. POST /v1/{workspace_url}/projects.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project title."
    },
    "resource_type": {
      "type": "string",
      "enum": [
        "arb",
        "properties",
        "windows_resx",
        "gettext_po",
        "markdown",
        "chrome_i18n",
        "qt_linguist_ts",
        "txt",
        "standard_ini",
        "android_xml",
        "ios_strings",
        "twine_txt",
        "rails_yaml",
        "php_define",
        "symfony2_yaml",
        "json_go_i18n",
        "angular_translate_json",
        "react_intl_json",
        "i18next_json",
        "standard_json",
        "csv",
        "xliff",
        "html"
      ],
      "description": "Resource file type, which fixes the import/export format (e.g. standard_json, i18next_json, android_xml, ios_strings, gettext_po, xliff)."
    },
    "source_language": {
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*$",
      "description": "Source language code, e.g. en or en-GB."
    },
    "target_languages": {
      "description": "Target language codes, e.g. [\"de\",\"fr\"].",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*$"
      }
    },
    "description": {
      "description": "Optional description, up to 512 characters.",
      "type": "string",
      "maxLength": 512
    }
  },
  "required": [
    "workspace_url",
    "title",
    "resource_type",
    "source_language"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List a project's resource files: name, locale and links (including a download link). GET .../projects/{project_url}/resources.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "locale_in_file_name": {
      "description": "Whether file names carry the locale: ALL (default), TARGETS or NONE.",
      "type": "string",
      "enum": [
        "ALL",
        "TARGETS",
        "NONE"
      ]
    },
    "add_iso2_slug": {
      "description": "Always add the iso2_slug parameter to the rendered file URLs.",
      "type": "boolean"
    },
    "branch": {
      "description": "Project branch name. Default: the project's default branch. An unknown branch is HTTP 422.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "workspace_url",
    "project_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Download one resource file as text, in one language. file_name is the file name as list_resources shows it (the folder goes in `path`). Long files are cut at 40000 characters (truncated: true); use request_export for a full copy. GET .../projects/{project_url}/resources/{file_name}.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "file_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Resource file name, e.g. messages_de.properties."
    },
    "path": {
      "description": "Folder of the file, when the file name alone is not unique.",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "language": {
      "description": "Locale code to export (overrides the locale in the file name), e.g. de.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*$"
    },
    "branch": {
      "description": "Project branch name. Default: the project's default branch. An unknown branch is HTTP 422.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "blank_content_handling": {
      "description": "What to export for a segment with no translation in the target language.",
      "type": "string",
      "enum": [
        "fallback",
        "use_source",
        "master_locale",
        "keep",
        "blank",
        "skip"
      ]
    },
    "filter_by_status": {
      "description": "Only export target segments in this state.",
      "type": "string",
      "enum": [
        "ALL",
        "TRANSLATED_AND_APPROVED",
        "TRANSLATED_AND_REVIEWED",
        "APPROVED",
        "REVIEWED"
      ]
    },
    "html_encoding": {
      "description": "How HTML in a segment is escaped.",
      "type": "string",
      "enum": [
        "RAW",
        "ESCAPE",
        "CDATA"
      ]
    }
  },
  "required": [
    "workspace_url",
    "project_url",
    "file_name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: upload one text resource file (JSON, properties, XLIFF, PO, ...) into a project. The language comes from the file name or from `language`. The import flags decide whether existing segments are changed or deactivated: with updating or deactivation on, translations already in Lingohub can be overwritten or switched off, so state the flags you want. Never retried. POST .../projects/{project_url}/resources.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "file_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "File name with extension, e.g. en.json."
    },
    "content": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000000,
      "description": "The file text (UTF-8), up to 1000000 characters."
    },
    "path": {
      "description": "Folder the file is uploaded to; set it when the file name collides with another file (HTTP 406).",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "language": {
      "description": "Locale of this file (overrides the locale in the file name), e.g. de.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*$"
    },
    "branch": {
      "description": "Project branch name. Default: the project's default branch. An unknown branch is HTTP 422.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "source_create_new": {
      "description": "If this is a source-language file: create new segments.",
      "type": "boolean"
    },
    "source_update_existing": {
      "description": "If this is a source-language file: update changed segments.",
      "type": "boolean"
    },
    "source_deactivate_missing": {
      "description": "If this is a source-language file: deactivate segments missing from the file.",
      "type": "boolean"
    },
    "target_create_new": {
      "description": "If this is a target-language file: create new segments.",
      "type": "boolean"
    },
    "target_update_existing": {
      "description": "If this is a target-language file: update changed translations (overwrites existing ones).",
      "type": "boolean"
    },
    "target_deactivate_missing": {
      "description": "If this is a target-language file: deactivate segments missing from the file.",
      "type": "boolean"
    }
  },
  "required": [
    "workspace_url",
    "project_url",
    "file_name",
    "content"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, DESTRUCTIVE: delete a resource container: the source-language file AND all its target-language files with their translations. file_name and path must address the source-language file. This cannot be undone through the API. Never retried. DELETE .../projects/{project_url}/resources/{file_name}.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "file_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "File name of the SOURCE-language file, as list_resources shows it."
    },
    "path": {
      "description": "Folder of the source-language file.",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "branch": {
      "description": "Project branch name. Default: the project's default branch. An unknown branch is HTTP 422.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "workspace_url",
    "project_url",
    "file_name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Start an asynchronous export of a project's resource files as a ZIP. It creates an export job and changes no project data. Returns the export id; poll get_export until its status is SUCCESS to get the download URL. Without filters it exports every file and language. POST .../projects/{project_url}/exports.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "file_paths": {
      "description": "Only these files, with the locale placeholder as shown in Lingohub, e.g. config/locales/%{locale}/messages.yml.",
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 500
      }
    },
    "languages": {
      "description": "Only these language codes, e.g. [\"en\",\"de\"].",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*$"
      }
    },
    "export_format": {
      "description": "Override the export format of the project type.",
      "type": "string",
      "enum": [
        "strings.ios",
        "xml.android.resources",
        "properties",
        "standard_json"
      ]
    },
    "branch": {
      "description": "Project branch name. Default: the project's default branch. An unknown branch is HTTP 422.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "workspace_url",
    "project_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Status of an export started with request_export: overall and per-file status (NEW, SCHEDULED, PROCESSING, SUCCESS, SKIPPED, ERROR), error details and, when done, the pre-signed download URL of the ZIP. GET .../projects/{project_url}/exports/{export_id}.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "export_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "^[A-Za-z0-9_-]+$",
      "description": "Export id from request_export, e.g. reg_18USq6822XIv-19847171."
    }
  },
  "required": [
    "workspace_url",
    "project_url",
    "export_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the context images (screenshots that show translators where a text is used) of a project, with connected-segment counts and processing status. Paginated; page is zero-based. GET .../projects/{project_url}/contextImages.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "page": {
      "description": "Zero-based page index (default 0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    },
    "size": {
      "description": "Results per page, 1-100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "workspace_url",
    "project_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, DESTRUCTIVE: delete one context image and its connections to text segments. Never retried. DELETE .../projects/{project_url}/contextImages/{image_id}.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "image_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "pattern": "^[A-Za-z0-9_-]+$",
      "description": "Context image id from list_context_images, e.g. ci_18USq6822XIv-19847171."
    }
  },
  "required": [
    "workspace_url",
    "project_url",
    "image_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: push the project's resource files to its linked Git repository (GitHub, GitLab, Bitbucket or Azure DevOps; the connection must already exist). Depending on push_type this commits to a branch or opens a pull request, so it changes the user's repository. Never retried. POST .../projects/{project_url}/push.

{
  "type": "object",
  "properties": {
    "workspace_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Workspace URL slug (e.g. \"lingohub-demo\"); list_projects returns it as workspace_url."
    },
    "project_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Project URL slug (e.g. \"feature-demo\"); list_projects returns it as project_url."
    },
    "push_type": {
      "description": "PUSH commits directly; PULL_REQUEST opens a pull/merge request. Default: the connection's setting.",
      "type": "string",
      "enum": [
        "PUSH",
        "PULL_REQUEST"
      ]
    },
    "branch": {
      "description": "Branch to push to. Default: the repository connection's default branch.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "commit_message": {
      "description": "Commit message. Default: generated.",
      "type": "string",
      "maxLength": 500
    },
    "commit_description": {
      "description": "Extended commit description.",
      "type": "string",
      "maxLength": 2000
    },
    "path": {
      "description": "Only push resource files under this path.",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "language": {
      "description": "Only push this language.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,8})*$"
    },
    "pull_request_branch": {
      "description": "Branch to create for the pull request (PULL_REQUEST only).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pull_request_title": {
      "description": "Pull request title (PULL_REQUEST only).",
      "type": "string",
      "maxLength": 300
    },
    "pull_request_description": {
      "description": "Pull request description (PULL_REQUEST only).",
      "type": "string",
      "maxLength": 4000
    }
  },
  "required": [
    "workspace_url",
    "project_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}