Customize segmentation with SRX - Phrase Developer Hub

Segmentation rules control where source text is split into segments before translation. This guide shows how to write those rules in SRX (Segmentation Rules eXchange) format and manage them through the Phrase TMS (Translation Management System) API.

Quickstart

The simplest call that confirms your token reaches the segmentation rules API lists the rules already in your organization:

curl "https://cloud.memsource.com/web/api2/v1/segmentationRules?pageSize=1" \
  --header "Authorization: Bearer YOUR_TOKEN"

A 200 response with a content array means you are connected and authorized. The base host depends on your region, and the token is set up in Prerequisites below.

{
  "content": [
    {
      "uid": "abcd1234",
      "name": "German with Co. exception",
      "filename": "german.srx",
      "locale": "de",
      "language": "de",
      "primary": false
    }
  ],
  "pageNumber": 0,
  "pageSize": 1,
  "totalElements": 1,
  "totalPages": 1
}

Prerequisites

Requirement	Notes
Phrase account with TMS access	A Translation Management System plan that includes segmentation rules.
Internal role	The token’s user needs an `ADMIN` or `PROJECT_MANAGER` role. Creating or replacing a rule also needs the `setupServer` access right.
Authentication set up	A valid Phrase token passed as `Authorization: Bearer`. See the TMS authentication reference.

The two rule formats

Phrase TMS accepts custom segmentation rules in two formats:

Format	Use case
XLSX	A list of abbreviations that should not trigger a segment break (for example “Dr.”, “approx.”). Two variants: `ABBR_UPPER_NUM` (no break before whitespace plus a number, symbol, or capitalized word) and `ABBR_NUM` (no break before whitespace plus a number).
SRX	Full regular-expression-based rules, for segmentation logic beyond a simple abbreviation exception list.

Segmentation determines where segment boundaries fall (typically at sentence ends), which directly affects translation memory (TM) match quality. A job (a file sent for translation) segmented differently than the TM it is leveraged against will get lower or no matches, so the rules that shipped with a job need to match the rules behind its TM.

Phrase’s SRX rules are character-based: only a single character can act as the segment separator. A group of characters (for example a tag like <p>) cannot be used as a separator.

SRX 2.0 structure

An SRX document has a header (global options) and a body (the rules):

<?xml version="1.0" encoding="UTF-8"?>
<srx xmlns="http://www.lisa.org/srx20" version="2.0">
  <header segmentsubflows="yes" cascade="no">
    <formathandle type="start" include="no"/>
    <formathandle type="end" include="yes"/>
    <formathandle type="isolated" include="no"/>
  </header>
  <body>
    <languagerules>
      <languagerule languagerulename="default">
        <rule break="no">
          <beforebreak>([A-Z]\.){2,}</beforebreak>
          <afterbreak>\s</afterbreak>
        </rule>
        <rule break="yes">
          <beforebreak>\.</beforebreak>
          <afterbreak>\s</afterbreak>
        </rule>
      </languagerule>
    </languagerules>
    <maprules>
      <languagemap languagepattern=".*" languagerulename="default"/>
    </maprules>
  </body>
</srx>

header: cascade controls whether more than one matching languagemap can apply its rules in sequence (yes) or only the first match is used (no, the SRX 1.0-compatible default). segmentsubflows controls whether text inside sub-flows (for example footnotes) is segmented too. formathandle controls whether inline formatting codes at the start, end, or isolated position of a segment are included in it.
languagerules: one or more named groups of rule elements, evaluated top to bottom. Each rule is either break="yes" (this is a valid segment boundary) or break="no" (suppress a break here, even if a later rule would otherwise break). A rule matches when the text immediately before the candidate break point matches beforebreak and the text immediately after it matches afterbreak.
maprules: maps a language code pattern (languagemap languagepattern, a regular expression like .* or (DE|de).*) to one of the named languagerule groups, so different languages can use different rule sets.

The example above is the canonical default rule set: break after a period followed by whitespace, unless the period follows a run of single capital letters with periods (for example do not break after “U.S.” or “U.K.”).

Worked example: upload a language-specific exception rule

Say German jobs keep breaking at “Co.” in company names like “GmbH & Co. KG”. The fix is a German-only SRX file that suppresses the break after “Co.”, then uploading it as a segmentation rule for the German locale (the language-plus-region code that identifies a translation direction, like de or de-AT). 1. Write the SRX file. Add a languagerule group with the break="no" rule listed before the general break="yes" rule, so it takes precedence at that position, and map it to German locales:

<languagerules>
  <languagerule languagerulename="German">
    <rule break="no">
      <beforebreak>\bCo\.</beforebreak>
      <afterbreak>\s</afterbreak>
    </rule>
    <rule break="yes">
      <beforebreak>\.</beforebreak>
      <afterbreak>\s</afterbreak>
    </rule>
  </languagerule>
</languagerules>
<maprules>
  <languagemap languagepattern="(DE|de).*" languagerulename="German"/>
</maprules>

2. Upload it. POST /api2/v1/segmentationRules streams the file as the request body and takes a segRule header carrying the rule’s metadata as a JSON object (name, locale, primary, filename):

curl --request POST "https://cloud.memsource.com/web/api2/v1/segmentationRules" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header 'segRule: {"name":"German with Co. exception","locale":"de","primary":false,"filename":"german.srx"}' \
  --data-binary @german.srx

A 201 response returns the created rule, including the uid you use to get, edit, export, or replace it later:

{
  "uid": "abcd1234",
  "name": "German with Co. exception",
  "filename": "german.srx",
  "locale": "de",
  "language": "de",
  "primary": false,
  "dateCreated": "2026-09-07T10:00:00Z"
}

Set primary to true to make this the default rule for the German locale across the organization. New rules take effect at job import time, so re-import affected jobs for the change to apply.

When the upload fails

403 Forbidden means the token’s user is missing the required role or access right. Listing rules needs an ADMIN or PROJECT_MANAGER role; creating or replacing a rule additionally needs the setupServer access right. Use a token for a user who has both, rather than retrying the same call.

A rule that never fires is usually a separator problem, not a syntax error. Phrase segments on a single character, so a beforebreak or afterbreak that depends on a multi-character separator (like a <p> tag) will not match. Rewrite the rule around a single-character boundary.

For the full list of response codes, see Error handling and limits.

Managing rules via the API

Task	API operation
List segmentation rules	List segmentation rules
Create a segmentation rule	Create segmentation rule
Get a segmentation rule	Get segmentation rule
Edit a segmentation rule	Edit segmentation rule
Export a segmentation rule (download its SRX/XLSX file)	Export segmentation rule
Export the default rules for a locale, as a starting point	Export default segmentation rules
Replace a rule’s underlying file	Replace segmentation rule file

When listing rules, the language and languages query parameters are mutually exclusive; passing both returns 400 Bad Request. The same actions are also available in the TMS web UI under Project Settings → Segmentation, where default rules can be exported as a starting point and custom rules uploaded as primary or secondary rule sets.

Rate limits

The segmentation rules endpoints share the standard Phrase TMS limit of 6,000 requests per minute for logged-in users, and return 429 Too Many Requests when it is exceeded. Back off and retry rather than looping on the error. See Handling API rate limits for the details.

Troubleshooting

If a call keeps failing after the fixes above, check the current Phrase TMS Limits and the Segmentation Rules (TMS) support article for the source-of-truth values and UI behavior. For account-specific problems, contact Phrase support; for help writing the API calls themselves, an AI tool with this page in context is often faster.

Next steps

Segmentation Rules API

Full request and response reference for every segmentation rules endpoint.

SRX 2.0 specification

The complete SRX standard from the Okapi Framework, for advanced rule authoring.

Last reviewed: September 2026. API changes are recorded in the changelog.

​Quickstart

​Prerequisites

​The two rule formats

​SRX 2.0 structure

​Worked example: upload a language-specific exception rule

​When the upload fails

​Managing rules via the API

​Rate limits

​Troubleshooting

​Next steps

Segmentation Rules API

SRX 2.0 specification

Quickstart

Prerequisites

The two rule formats

SRX 2.0 structure

Worked example: upload a language-specific exception rule

When the upload fails

Managing rules via the API

Rate limits

Troubleshooting

Next steps