# Phrase API MCP

> Phrase (Software Localization API) connects your AI agent directly to localization projects. Manage full software translation lifecycles—including creating new projects, adding locales, and updating thousands of translation keys—without opening the Phrase web UI or leaving your IDE.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** i18n, l10n, translation-management, software-localization, phrase-api

## Description

**Phrase API MCP Server: Your localization workflow, handled.**

You don't wanna open the Phrase web UI just to tweak a few strings or set up a new project. This server hooks your AI client right into your entire software translation lifecycle. You manage everything—from creating brand-new keys that live in your codebase all the way through downloading final XLIFF files. Your agent handles complex localization tasks using natural language, so you never leave your IDE.

**Project Management: Setting Up and Tearing Down Workspaces**

*`create_project`*: You can set up an entirely new localization project under your Phrase account when you need one. *`list_projects`*: Need to see what projects are active? This tool gives you a simple list of every single thing you've got running. *`get_project`*: If you know the ID, this fetches all the full status and metadata for that project. You can modify core settings using `update_project`, like renaming it or changing its primary scope. Conversely, if a project is dead weight, `delete_project` wipes out the entire thing—it's permanent, so be careful.

**Target Language (Locale) Control: Managing Supported Languages**

The server gives you total control over your supported languages. *`list_locales`*: This tool shows every language setting configured for a specific project. *`get_locale`*: Need the details on just one language? Use this to fetch all the info for that single locale. You can add new target languages using `create_locale`, or you can use `update_locale` if you need to change its settings, maybe renaming it or updating its default status. If a language is totally unnecessary, `delete_locale` removes the whole setting and cleans out all associated translations.

**Key Management: The Source Code Strings**

*`list_keys`*: This tool lets you pull up every single translation key tied to a project. *`get_key`*: You can retrieve all details for one specific, existing translation key if you need them. When your codebase adds a brand-new string that needs translations, `create_key` generates it as a unique key ready for action. If a key is obsolete or wrong, `delete_key` removes it—remember, this one's tricky.

**Translation Data: Inputting and Manipulating Text**

You don't have to manually type everything in. *`create_translation`*: This lets you input a brand-new translated value for a specific key/locale combo. You can change that actual text later using `update_translation`. If the source data changes, you modify it with `update_key` to update the key's metadata or definition. To keep your translations fresh from outside sources, use `upload_file` to ingest external localization files, like spreadsheets, into a project.

**Retrieval and Export: Getting What You Need**

*`list_translations`*: This shows you all the current translation strings available for a specific key and project. *`download_file`*: When it’s time to deploy, this tool pulls down all translations into specified formats like JSON or XLIFF. *`get_locale`* also helps pull detailed info about one language setting within a project.

**The Bottom Line: Core Capabilities in Action**

Your agent can list every active software localization project you own. It'll add brand-new, unique strings—the keys—to your codebase that need translations. You manage the supported languages by creating or updating the list of locales for any given project. When text changes, it updates existing localized string values for a key and locale. Finally, when development needs files, it pulls down all translations for a project into specific file formats needed for deployment.

## Tools

### create_key
Generates a brand-new translation string (key) that must be added to the codebase.

### create_locale
Adds a new target language/region setting (locale) to an existing project.

### create_project
Sets up an entirely new localization project under your Phrase account.

### create_translation
Manually inputs a brand-new translated value for a specific key/locale combination.

### delete_key
Removes a translation key from the system. Use caution with this one.

### delete_locale
Deletes an entire language setting (locale) from a project, removing all associated translations.

### delete_project
Wipes out an entire localization project and all its contents. Permanent action.

### download_file
Pulls down the current translation data for a project into a specified file format (e.g., JSON or XLIFF).

### get_key
Retrieves all details about one specific, existing translation key.

### get_locale
Fetches detailed information for a single target language setting (locale) within a project.

### get_project
Gets the full status and metadata for an entire localization project by ID.

### list_keys
Lists every translation key currently associated with a specific project.

### list_locales
Shows all configured target languages (locales) for a given project.

### list_projects
Provides a simple list of every single localization project you have set up.

### list_translations
Lists the current translation strings available for a specific key and project.

### update_key
Modifies an existing translation key's metadata or definition.

### update_locale
Changes settings on an existing locale, such as renaming it or updating its default status.

### update_project
Applies changes to the main project settings, like changing the name or primary scope.

### update_translation
Changes the actual translated text for a given key and locale combination.

### upload_file
Ingests external localization files (like spreadsheets) to populate translations into a project.

## Prompt Examples

**Prompt:** 
```
List all my Phrase localization projects.
```

**Response:** 
```
I've retrieved your projects. You have 'Mobile App' (ID: proj_abc123) and 'Web Dashboard' (ID: proj_xyz789). Which one would you like to manage?
```

**Prompt:** 
```
Show me the locales configured for project proj_abc123.
```

**Response:** 
```
For project proj_abc123, I found 3 locales: English (en-US, default), German (de-DE), and Spanish (es-ES).
```

**Prompt:** 
```
Create a new translation key named 'login.button.submit' in project proj_abc123.
```

**Response:** 
```
Successfully created the translation key 'login.button.submit' in project proj_abc123.
```

## Capabilities

### List all localization projects
Retrieves a list of every active software localization project you own in Phrase.

### Create new translation keys
Adds brand-new, unique strings (keys) to your codebase that need translations.

### Manage target languages (locales)
Creates or updates the list of supported human languages for a specific project.

### Update translation text
Changes an existing localized string value for a given key and locale.

### Download localization files
Pulls down all translations for a project into specific file formats needed for deployment.

## Use Cases

### The Missing Locale Problem
A product manager notices that the 'German' language (de-DE) was never added to a new project. Instead of logging into Phrase and manually navigating setup menus, they prompt their agent: 'Check if German is available for Project XYZ.' The agent runs `list_locales` and confirms it's missing. They then instruct the agent to run `create_locale`, solving the issue in three steps.

### The Broken Key Sync
A developer refactors a feature and changes the key 'user.profile.avatar' to 'user.avatar.display'. Instead of manually updating every reference, they ask their agent to use `update_key` to rename the string across the entire project scope. This prevents broken translations in all target languages.

### The Initial Project Setup
A team starts a new product line and needs localization setup for English, Spanish, French, and Japanese. They prompt their agent to 'Start a new project called Global Site.' The agent runs `create_project` and then sequentially calls `create_locale` for all four languages, getting the entire scaffold ready instantly.

### The Translation Audit
A localization manager needs to audit all translations for a specific key ('welcome.message') across 15 different locales. They use `list_translations` and then prompt the agent to check if any locale is missing required data, ensuring no language falls out of sync.

## Benefits

- **Stop Context Switching:** You can run `list_projects` and then immediately jump into project management tasks (like calling `create_key`)—all from the chat window. No need to open a separate web browser tab.
- **Bulk Data Operations:** Need to update 50 translations? Use `upload_file` to ingest a spreadsheet of data, or use `update_translation` in a loop via your agent to fix multiple strings across different locales.
- **Full Lifecycle Control:** From initial setup (`create_project`) through maintenance (`list_locales`), this tool gives you full programmatic control over the entire localization structure. It's an end-to-end management system.
- **Code-Sync Management:** The `create_key` and `delete_key` tools let developers manage their source code strings (keys) directly from within the agent, keeping your codebase and Phrase perfectly synced instantly.
- **Deep Inspection:** Don't guess what you have. Use `get_project`, `list_locales`, or `get_key` to fetch precise data points—knowing exactly which locale is missing or which key needs updating before writing any code.

## How It Works

The bottom line is that your AI client executes a sequence of API calls, managing complex state transitions across projects and translations for you.

1. Subscribe to the server and provide your unique Phrase Access Token.
2. Ask your agent for a high-level goal, like 'I need to add Japanese support to the Dashboard project.'
3. The agent runs multiple tools (`list_projects` -> `create_locale` -> `update_project`) until the task is complete and confirms the changes.

## Frequently Asked Questions

**How do I use the create_key tool with Phrase API MCP Server?**
You tell your agent what key you need and where. For example: 'Create a new translation key called 'user.greeting.message' in the Main App project.' The agent handles the necessary syntax for `create_key`.

**Can I delete a whole localization project using Phrase API MCP Server?**
Yes, you use the `delete_project` tool. Be careful; this action is irreversible and wipes out all associated keys, locales, and translations within that project scope.

**Does list_locales show me if a locale is missing for a project?**
The `list_locales` tool shows you every configured language. If the required language isn't in the returned list, it means the locale needs to be added first using `create_locale`.

**What should I use if I have translations in a CSV file?**
Don't try to update them one by one. Use the `upload_file` tool and point it at your structured spreadsheet. This handles bulk data ingestion efficiently, updating many keys/translations simultaneously.

**What credentials do I need to connect before running list_projects?**
You must supply a valid Phrase Access Token. This token authorizes your agent to interact with your specific account and execute any commands, like listing projects.

**How does the get_project tool retrieve details about an existing project?**
It requires the unique Project ID. Once you provide that ID, the tool returns all metadata, including locale setup, key counts, and status information for that specific localization container.

**If I need to change a translation string, how does update_translation work?**
The `update_translation` tool requires three things: the Project ID, the Locale ID, and the new content. It overwrites the existing text for that specific key/language combination.

**Can I use download_file to get translations in multiple formats?**
Yes, `download_file` handles various file types. You specify the format you need (like JSON or CSV) and the scope of data, pulling all required translations into a single downloadable package.

**Can I list all translation keys for a specific project?**
Yes! Use the `list_keys` tool by providing the `project_id`. It will retrieve all translation keys configured for that project.

**How do I add a new language to my localization project?**
You can use the `create_locale` tool. You'll need to provide the `project_id`, the locale `name` (e.g., 'French'), and the locale `code` (e.g., 'fr-FR').

**Is it possible to update an existing project's name?**
Yes, the `update_project` tool allows you to modify properties like the project `name` and `main_format` using the `project_id`.