Core Concepts - Phrase Developer Hub

This page explains the data model behind the Style Guide API and how Style Guides, Rules, and Content Groups relate to each other and to TMS projects.

New integrations should use the v2 endpoints (POST /api/v2/styleguides, PUT /api/v2/styleguides/{id}). They accept a contentGroupId parameter that links the Style Guide to a Content Group and unlocks automatic rule application in TMS projects.

Style Guides

A Style Guide is a Markdown document that captures writing guidelines for a specific language — tone, grammar rules, terminology, and formatting conventions. An organization can have one Style Guide per Content Group and language. Key properties:

Language — BCP-47 locale code (e.g., en-GB, sv-SE). Each Style Guide is scoped to exactly one language.
Name and description — human-readable metadata updated on every revision.
Content Group — link to a Content Group (see below). Required when using v2 endpoints.

Versions

Every time a new Markdown file is uploaded to a Style Guide, a new version is created. Versions are immutable snapshots — you cannot edit a version’s file after creation, only supersede it with a new upload. Each version records:

Field	Description
`versionNumber`	Monotonically increasing integer
`name` / `description`	Metadata at the time of upload
`changeNotes`	Optional free-text summary of what changed (`versionChangeReason` on the request)
`fileName`, `fileSizeBytes`, `fileType`	File metadata

The Style Guide’s top-level name, description, and lastModifiedAt always reflect the latest version.

Rules

A Rule is a single writing instruction — for example, “Avoid passive voice in all user-facing content.”. Rules are used by AI Translation Agent and MT Optimize evaluate to improve translation quality.

Origins

Rules come from two sources:

Origin	How it works
Extracted	Automatically generated when a Style Guide is created or updated. Each distinct guideline in the Markdown file becomes a separate Rule, linked to the Style Guide.
Manual	Created directly via `POST /api/v1/rules`. Useful for rules that don’t belong to any Style Guide, or for adding guidelines incrementally.

Scope

Each Rule carries two independent scope dimensions: Content Group scope — which Content Groups this rule applies to:

allContentGroups: true — rule applies across every Content Group in the organization.
allContentGroups: false + non-empty contentGroupIds — rule applies only to the listed Content Groups.

Language scope — which languages this rule applies to:

allLanguages: true — rule applies to translations in every language.
allLanguages: false + non-empty languages — rule applies only to the listed locale codes.

Lifecycle

Extracted Rules start out linked to their source Style Guide (styleGuide field is populated). A Rule becomes unlinked (standalone) when a PATCH /api/v1/rules/{id} request does either of the following:

Edits the rule text.
Changes the content group or language scope in any way — including narrowing it, broadening it, or switching to allContentGroups: true / allLanguages: true. Resubmitting the exact same scope the rule already has is not a change and does not unlink it.

Because unlinking is permanent, PATCH /api/v1/rules/{id} requires you to confirm it explicitly: if the update would unlink the rule and the request does not set forceUnlink: true, the API returns 409 Conflict (RULE_UNLINK_REQUIRES_CONFIRMATION) and applies none of the requested changes. Retry the same request with forceUnlink: true to proceed. See Working with Rules for an example. Unlinking turns the rule into a manual rule. The original Style Guide is unchanged. When a new Style Guide version is uploaded, every rule still linked to that Style Guide is deleted and replaced by the freshly extracted set. Only rules that were already unlinked beforehand (via a prior forceUnlink: true edit) survive a new version upload as standalone rules. If the updated Style Guide file still contains an equivalent guideline, the newly extracted rule can duplicate one of these surviving standalone rules. Review standalone rules that originated from a Style Guide after uploading a new version, and remove any that now duplicate a freshly extracted rule.

Active and AI check flags

Each Rule has two toggles:

active — disabled rules are excluded from all checks and are not used by AI Translation Agent or MT Optimize.
aiCheckEnabled — when false, the rule is excluded from AI-powered Quality Assurance checks but is still used by AI Translation Agent and MT Optimize.

Content Groups

A Content Group is an identifier managed by the Content Group API (a separate service). It is a broader Platform concept that is used to organize Assets and Projects across logical groups. In case of Style Guides, a content group acts as a shared reference point that connects Style Guides and their Rules to TMS projects. Content Groups are created and managed outside this API. The Style Guide API accepts a Content Group ID as an opaque string — use the Content Group API to create and list groups.

How Everything Connects

Style Guide (language: en-GB)
  ├── linked to → Content Group "marketing"
  └── source of → Rules (each scoped to Content Group "marketing", language en-GB)

TMS Project
  └── linked to → Content Group "marketing"
        └── at translation time, applies all active Rules where:
              contentGroupIds contains "marketing" (or allContentGroups = true)
              AND languages contains job language (or allLanguages = true)

TMS project integration

In previous versions of the API, a TMS project had to be linked to a Style Guide per target language. With Content Groups, the workflow changes:

Create a Style Guide with a contentGroupId (v2 endpoint).
Link the TMS project to the same Content Group (via TMS project settings).
When a translation job runs, the AI Translation Agent and MT Optimize automatically pick up all active Rules whose content group and language scope match the job’s Content Group and target language.

This means a single Content Group can aggregate Rules from multiple Style Guides across languages, and one Style Guide can serve multiple projects through a shared Content Group.

Rule changes — whether made directly via the Rules API or triggered by uploading a new Style Guide version — take effect immediately for any running jobs in that Content Group. To avoid unintended effects on in-flight translations, make rule changes when no jobs for that Content Group are active. You can update and review rules before starting new jobs to verify they produce the expected results.

Summary

Resource	Scope	Created by
Style Guide	One per Content Group & language per organization	API upload (v1 or v2)
Version	One per file upload	Automatic on Style Guide create/update
Rule	Many per Style Guide; standalone rules also possible	Automatic extraction or manual creation
Content Group	Organization-wide	Content Group API

For step-by-step API usage, see Working with Rules and the API Documentation section in the left navigation.

​Style Guides

​Versions

​Rules

​Origins

​Scope

​Lifecycle

​Active and AI check flags

​Content Groups

​How Everything Connects

​TMS project integration

​Summary

Style Guides

Versions

Rules

Origins

Scope

Lifecycle

Active and AI check flags

Content Groups

How Everything Connects

TMS project integration

Summary