Style guides are centralized language guidelines that define how content should be written for a specific language or locale. They help ensure that tone, terminology, formatting, and output remain consistent across projects and teams.
Style guides are uploaded as Markdown (.md) files and stored in a shared library accessible from the Phrase Platform dashboard by selecting Assets in the left navigation menu. They can be attached and reused across projects in:
When a Markdown file is uploaded or a previous version is restored, Phrase automatically generates an AI-optimized version of the style guide. This version is used in AI workflows to improve AI Translation Agent and MT Optimize results without requiring custom instructions for every job. The AI-friendly style guide enables Phrase AI services to adapt tone and formality to user preferences, apply required terminology and wording, and follow locale-specific conventions.
While the AI Translation Agent considers both term bases and style guides, style guides do not directly enforce terminology from a term base. The use of style guides does not incur any additional AI Unit (AIU) cost.
Each style guide applies to exactly one locale (for example, en-US or de-DE). If multiple variants or use cases require different rules, separate style guides must be created.
Organizations can add up to 500 style guides.
Permissions
-
Only Platform organization Administrators can create, edit, delete, or set default style guides.
-
Project Managers can attach style guides to projects.
-
Linguists and Translators can view attached style guides in TMS and Strings editors.
File and Structure Requirements
-
One style guide in Markdown (.md) format per locale:
-
Maximum size: 150 KB
-
Images are not supported
-
-
Recommended structure:
-
Purpose and Scope
-
Voice and Tone
-
Grammar and Writing Rules
-
Terminology (approved and forbidden terms)
-
Locale Conventions
-
Formatting Standards
-
Content-Type Guidance
-
Troubleshooting and Error Style (if applicable)
Clear headings and structured rules improve both human readability and AI interpretation.
-
Below is an example of a complete, non‑conflicting style guide that can be adapted as required:
Locale: en-US
Use case: SaaS B2B Product – Help Center and UI
# Style Guide: EN-US – Help Center Articles ## 1. Purpose & Scope This style guide defines the writing standards for all **Help Center documentation** in **English (United States)**. It applies to: - How-to articles - Feature explanations - Troubleshooting guides - FAQ entries **Audience:** professional SaaS users in technical and business roles **Goal:** help users complete tasks quickly, confidently, and without confusion. --- ## 2. Voice & Tone Help Center content should sound: - **Clear and professional** - **Supportive and solution-focused** - **Confident, not promotional** We write as a guide helping users succeed — not as marketing copy. ### Tone principles | Do | Don’t | |---|------| | Be calm and direct | Be overly casual or chatty | | Focus on next steps | Focus only on what went wrong | | Use neutral language | Use sarcasm or humor | **Examples** - ✅ “If the connection fails, check your API token and try again.” - ❌ “Your token is wrong. Fix it.” --- ## 3. Grammar & Writing Style ### 3.1 Address the reader directly Use **you** to make instructions clear. - ✅ “You can manage users from the Admin page.” - ❌ “Users can be managed from the Admin page.” --- ### 3.2 Prefer active voice Active voice is shorter and easier to follow. - ✅ “Select **Save changes**.” - ❌ “Save changes should be selected.” --- ### 3.3 Keep sentences concise - Aim for **25 words or fewer** - One main idea per sentence - Break long explanations into steps or bullets --- ### 3.4 Use plain language Avoid unnecessary complexity. - ✅ “Start a new project.” - ❌ “Initiate the creation of a new project.” --- ## 4. Terminology & Consistency ### 4.1 Use approved terms Use product and feature names exactly as defined. - Keep capitalization consistent - Do not invent synonyms for key concepts **Example** - ✅ “workspace” - ❌ “space,” “project area,” “environment” --- ### 4.2 Define uncommon acronyms Common terms (API, URL) do not need definition. Internal or uncommon acronyms should be explained on first use. - ✅ “Single Sign-On (SSO)” - ❌ “SSO” without context --- ### 4.3 US English conventions Always use **en-US spelling**. - ✅ “customize,” “behavior” - ❌ “customise,” “behaviour” --- ## 5. Formatting & Markdown Standards ### 5.1 Headings Use clear, task-based headings. - ✅ “Reset your password” - ❌ “Password resetting process overview” Heading hierarchy: - `#` Article title - `##` Main sections - `###` Subsections only when needed --- ### 5.2 Lists Use numbered lists for sequences: 1. Open **Settings** 2. Select **Billing** 3. Choose **Change plan** Use bullets for options: - Admins can manage users - Editors can update content --- ### 5.3 UI elements Format UI labels consistently: - Buttons: **bold** - Navigation paths: use arrows Example: Go to **Settings → Billing → Change plan**. --- ### 5.4 Links Links must describe the destination. - ✅ “See the billing guide” - ❌ “Click here” --- ## 6. Standard Article Structure Every Help Center article should follow this structure: ### 1. Summary Start with 1–2 sentences explaining the outcome. > This article explains how to change your subscription plan. --- ### 2. Prerequisites (optional) List requirements upfront. - Admin permissions - Active subscription --- ### 3. Step-by-step instructions Steps should be: - Action-oriented - One action per step - Written as commands Example: 1. Go to **Settings**. 2. Select **Billing**. 3. Choose **Change plan**. --- ### 4. Expected result Tell the user what should happen. > Your new plan takes effect immediately after confirmation. --- ### 5. Next steps (optional) Provide related actions or links. - Manage invoices - Update payment method --- ## 7. Troubleshooting & Errors ### 7.1 Be reassuring - ✅ “We couldn’t connect. Please try again.” - ❌ “Connection failed. Critical error.” --- ### 7.2 Focus on solutions Always include what the user should do next. - Check credentials - Confirm permissions - Contact support if needed --- ### 7.3 Never blame the user Avoid language like: - “You did something wrong” - “Invalid input” (without explanation) Preferred: > “The token may be expired. Generate a new one and retry.” --- ## 8. Do / Don’t Summary ### Do - Write task-focused, step-based content - Use consistent terminology - Keep sentences short and direct - Use descriptive headings and links - Maintain a calm, supportive tone ### Don’t - Add marketing language - Use idioms or slang - Mix terms for the same concept - Blame the user in troubleshooting - Write long paragraphs without structure --- ## Example (Preferred) To change your plan: 1. Go to **Settings → Billing** 2. Select **Change plan** 3. Choose an option and select **Confirm**
Style guides are created and managed in the shared library accessible from the Phrase Platform dashboard by selecting in the left navigation menu. The page lists all style guides available in your organization.
If logged in to Phrase TMS, Phrase Strings, or Phrase Studio, select from the left navigation to open the shared library.
Create a Style Guide
To create a new style guide as Administrator, follow these steps:
-
In the page, select New style guide.
The page is displayed.
-
Configure , and (optional).
Name must be unique.
-
Drag and drop or select Upload file to upload the style guide as a Markdown (.md) file.
-
Click Create style guide.
Phrase automatically generates the AI‑friendly version from the uploaded file. This might take a few seconds.
The new style guide is added to the page.
-
Optionally, select Set as default.
When attaching style guides to new projects, Phrase suggests the default style guide if no specific guide is set. The suggestion can be overriden.
Tip
Remove any language-specific rules from the default style guide.
Edit or Delete Style Guides
Style guides can be updated, versioned, shared, or removed. From the page, use the menu next to a listed style guide to:
-
Set as default
Mark the style guide as the suggested default when no specific guide is selected in new projects. The default suggestion can be overridden at project level.
-
Delete
Deleting a style guide does not retroactively change completed or ongoing jobs. Only the latest version of a style guide can be attached to new projects.
Tip
Before deleting a style guide, verify:
-
Whether it is still attached to active projects or templates
-
Whether it must be retained for compliance or historical reference
-
-
Copy public link
Generate a read-only link for sharing with external stakeholders who do not have a Phrase account.
In the page, select the pencil icon next to a style guide to open the page and update its metadata, Markdown file or default status.
An optional description of the changes can be added before saving to include it in the version history. A new version is created only when the Markdown file is replaced. This version applies only to new jobs or to jobs that have not yet started in projects where the style guide is used.
Manage Version History
Style guides maintain a version history in case of changes to existing versions.
To view the version history and restore versions of a style guide, follow these steps:
-
In the page, click on a style guide in the list to open its detail page.
-
Select Version history from the
at the top of the detail page.
The panel is displayed.
-
Select an older version listed in the section.
The older version is displayed.
-
If required, select Edit from this version in the .
The previous version is restored to create a new active version based on it.
Restoring or editing from an earlier version does not overwrite history.
Once a style guide has been created in the library, it can be attached to projects in Phrase TMS, Phrase Strings, and Phrase Studio.
General behavior across products:
-
Style guides are configured per target language and apply to the entire project. They are applied during pre-translation when using the AI Translation Agent, or as a post-editing step when using MT Optimize.
-
When a new version of the style guide is created, it applies only to new jobs. Ongoing jobs continue using the version active at the time of creation.
-
AI features use the attached style guide automatically when supported. Style guides do not affect locked segments, as MT Optimize does not modify them. By default, the AI Translation Agent also leaves segments from a Translation Memory (TM) unaffected, though this can be configured in the pre-translation settings.
Phrase TMS
Style guides can be attached to a project or project template.
-
When creating or editing a project or project template, navigate to the section and select a style guide per target locale.
The system may automatically pre-select the most relevant style guide based on locale matching. The pre-selection can always be overridden or cleared.
Note
Not supported in classic project template view.
-
Changes to project templates affect only newly created projects and jobs. Existing projects are not retroactively updated.
-
Attached style guides are visible to linguists in the
pane of the CAT web editor as a read-only resource.
-
Vendors in shared projects cannot modify a buyer’s assigned style guide.
-
In shared job scenarios, vendors can use the assigned style guide but cannot change project-level configuration.
-
Phrase Strings
-
In a project page, navigate to the tab and select a style guide per target locale.
-
Attached style guides are visible to translators at the key level in the menu of the Strings editor sidebar.
Phrase Studio
-
When creating a project, select a style guide for each target language added to the project.
The system may automatically pre-select the most relevant style guide based on locale matching. The pre-selection can always be overridden or cleared.
-
The AI-friendly version of the style guide is applied behind the scenes as contextual input for AI Translation Agent workflows.