> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phrase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize segmentation with SRX

> Understand the SRX and XLSX segmentation rule formats and manage custom segmentation rules through the Phrase TMS API.

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:

```bash theme={null}
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](#prerequisites) below.

```json theme={null}
{
  "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](/en/api/tms/latest/authentication).   |

## 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.

<Note>
  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.
</Note>

## SRX 2.0 structure

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

```xml theme={null}
<?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:

```xml theme={null}
<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`):

```bash theme={null}
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:

```json theme={null}
{
  "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

<Warning>
  **`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.
</Warning>

<Warning>
  **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.
</Warning>

For the full list of response codes, see [Error handling and limits](/en/guides/build-a-tms-plugin/error-handling-and-limits).

## Managing rules via the API

| Task                                                       | API operation                                                                                                |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| List segmentation rules                                    | [List segmentation rules](/en/api/tms/latest/segmentation-rules/list-segmentation-rules)                     |
| Create a segmentation rule                                 | [Create segmentation rule](/en/api/tms/latest/segmentation-rules/create-segmentation-rule)                   |
| Get a segmentation rule                                    | [Get segmentation rule](/en/api/tms/latest/segmentation-rules/get-segmentation-rule)                         |
| Edit a segmentation rule                                   | [Edit segmentation rule](/en/api/tms/latest/segmentation-rules/edit-segmentation-rule)                       |
| Export a segmentation rule (download its SRX/XLSX file)    | [Export segmentation rule](/en/api/tms/latest/segmentation-rules/export-segmentation-rule)                   |
| Export the default rules for a locale, as a starting point | [Export default segmentation rules](/en/api/tms/latest/segmentation-rules/export-default-segmentation-rules) |
| Replace a rule's underlying file                           | [Replace segmentation rule file](/en/api/tms/latest/segmentation-rules/replace-segmentation-rule-file)       |

<Note>
  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.
</Note>

## 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](/en/api/tms/latest/handling-api-rate-limits) for the details.

## Troubleshooting

If a call keeps failing after the fixes above, check the current [Phrase TMS Limits](https://support.phrase.com/hc/en-us/articles/5784117234972-Phrase-TMS-Limits) and the [Segmentation Rules (TMS)](https://support.phrase.com/hc/en-us/articles/5709712126876-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

<CardGroup cols={2}>
  <Card title="Segmentation Rules API" icon="scissors" href="/en/api/tms/latest/segmentation-rules/list-segmentation-rules">
    Full request and response reference for every segmentation rules endpoint.
  </Card>

  <Card title="SRX 2.0 specification" icon="book" href="https://okapiframework.org/wiki/index.php/SRX">
    The complete SRX standard from the Okapi Framework, for advanced rule authoring.
  </Card>
</CardGroup>

*Last reviewed: September 2026. API changes are recorded in the [changelog](/en/changelog).*