angular-i18n-mcp

Angular i18n MCP Server

This MCP server provides tools to manage Angular internationalization (i18n) using XLIFF 1.2 and 2.0 formats. It integrates with ng-extract-i18n-merge to automate the extraction and merging of translation strings.

Why use this MCP server?

Managing translation files (XLIFF) in Angular projects can be challenging for AI models due to the size and complexity of the XML files. This MCP server solves this by:

• LLM-Friendly Interface: Provides concise JSON output for translation units, avoiding the need for AI to parse large XML files.
• Accurate Extraction: Leverages the Angular CLI to extract strings directly from source code, ensuring all i18n attributes are captured.
• Structured Updates: Automatically handles XML serialization and ensures proper escaping of special characters, maintaining the integrity of your translation files.
• Efficient Workflow: Supports listing only new translations and performing bulk updates, making the localization process faster and more reliable.

Features

• Extract i18n: Runs the Angular CLI command to extract strings and merge them into target locale files.
• List New Translations: Identifies units that are newly added and haven't been translated yet (marked with state="initial").
• List All Translations: Provides a paginated list of all translation units.
• Update Translations: Updates multiple translation units in a single call.
• I18N Settings: Retrieves the i18n configuration from angular.json.

Prerequisites

• Node.js installed.
• An Angular project configured for i18n as described in the Angular i18n Guide.
• The project should be configured with ng-extract-i18n-merge:

  ng add ng-extract-i18n-merge

• Angular configuration (angular.json) should define the target locales and the translation format (xlf or xlf2).

Configuration

While this is a standard MCP server that works with any MCP-compatible client, the following configuration example is specifically for the Gemini CLI.

The server requires configuration in .gemini/settings.json. You can place this file in either:

• Your user home directory: ~/.gemini/settings.json
• The project root directory: ./.gemini/settings.json

Add the following to your configuration:

{
  "mcpServers": {
    "angular-i18n": {
      "command": "npx",
      "args": ["-y", "angular-i18n-mcp"],
      "env": {
        "LOCALE_DIR": "src/locale"
      }
    }
  }
}

Environment Variables:

• LOCALE_DIR: (Optional) The directory where translation files are stored. Defaults to src/locale.

It is recommended to add src/locale to your .geminiignore file to prevent Gemini from reading large translation files directly or attempting manual updates.

It is strongly recommended to use I18N metadata for translation to provide additional context for translators. This will allow the AI to provide better suggestions and translations.

Tools

extract_i18n

• Extracts strings from the source code and merges them into the .xlf files.

get_i18n_settings

• Retrieves the i18n section from angular.json to identify configured locales and source language.

list_new_translations

• Lists newly added translation units that haven't been translated yet (marked with state="initial").
• Arguments:
• locale: The target language code (e.g., de).
• page (optional): Page number for pagination.
• pageSize (optional): Number of units per page.

list_all_translations

• Lists all translation units in a locale file.
• Arguments:
• locale: The target language code.
• page (optional): Page number.
• pageSize (optional): Number of units per page.

update_translations

• Updates multiple translation units (up to 50) in a single call. Sets the state to translated.
• Arguments:
• locale: The target language code.
• updates: An array of objects, each containing id and translation.