Skip to main content
Glama
realskyrin

Android i18n MCP Server

by realskyrin

Android i18n MCP Server

An MCP (Model Context Protocol) server that automatically translates Android app string resources to multiple languages by detecting changes in the default strings.xml files using Git diff.

📖 Project Introduction Article (Chinese)

Screenshots

Related MCP server: Lokalise MCP Tool

Features

  • Automatically detects new or modified strings in default strings.xml files using Git diff

  • Translates to up to 28 languages (configurable via environment variable)

  • Preserves Android string formatting placeholders (%s, %d, %1$s, etc.)

  • Supports multiple Android modules

  • Batch translation for better performance

  • Only translates changed strings to save API costs

  • Configurable language selection to optimize API usage

Supported Languages

The server supports translation to 28 languages. You can configure which languages to translate to using the TRANSLATION_LANGUAGES environment variable.

All Supported Languages:

  • zh-CN - Simplified Chinese (values-zh-rCN)

  • zh-TW - Traditional Chinese Taiwan (values-zh-rTW)

  • zh-SG - Traditional Chinese Singapore (values-zh-rSG)

  • zh-HK - Traditional Chinese Hong Kong (values-zh-rHK)

  • zh-MO - Traditional Chinese Macau (values-zh-rMO)

  • en - English (values-en)

  • es - Spanish (values-es)

  • hi - Hindi (values-hi)

  • fr - French (values-fr)

  • ar - Arabic (values-ar)

  • bn - Bengali (values-bn)

  • pt - Portuguese (values-pt)

  • ru - Russian (values-ru)

  • ur - Urdu (values-ur)

  • id - Indonesian (values-id)

  • de - German (values-de)

  • ja - Japanese (values-ja)

  • sw - Swahili (values-sw)

  • mr - Marathi (values-mr)

  • te - Telugu (values-te)

  • tr - Turkish (values-tr)

  • ko - Korean (values-ko)

  • ta - Tamil (values-ta)

  • vi - Vietnamese (values-vi)

  • az - Azerbaijani (values-az)

  • be - Belarusian (values-be)

  • it - Italian (values-it)

  • uk - Ukrainian (values-uk)

Installation

  1. Clone the repository:

git clone <repository-url>
cd android-i18n-mcp
  1. Install dependencies:

npm install
  1. Build the project:

npm run build
  1. Configure environment variables:

cp .env.example .env

Edit .env file with your configuration:

ANDROID_PROJECT_ROOT=/path/to/your/android/project
TRANSLATION_PROVIDER=openai
TRANSLATION_API_KEY=your_api_key_here
# Optional:
TRANSLATION_API_BASE_URL=https://api.openai.com/v1
TRANSLATION_MODEL=gpt-4o-mini
# Comma-separated list of languages to translate (optional, defaults to all 28 languages)
TRANSLATION_LANGUAGES=zh-CN,es,fr,de,ja,ko
# Source language setting (optional, defaults to 'en'. If your default strings.xml uses another language like Chinese, set it to 'zh-CN')
TRANSLATOR_SOURCE_LANGUAGE=en

MCP Configuration

Add this server to your MCP client configuration (e.g., Cursor,Claude Desktop):

{
  "mcpServers": {
    "android-i18n": {
      "command": "node",
      "args": ["/path/to/android-i18n-mcp/build/index.js"],
      "env": {
        "ANDROID_PROJECT_ROOT": "/path/to/your/android/project",
        "TRANSLATION_PROVIDER": "openai",
        "TRANSLATION_API_BASE_URL": "https://api.deepseek.com/v1",
        "TRANSLATION_API_KEY": "your_api_key_here",
        "TRANSLATION_LANGUAGES": "zh-CN,es,fr,de",  // Optional: specific languages
        "TRANSLATOR_SOURCE_LANGUAGE": "en"  // Optional: source language (default: en)
      }
    }
  }
}

Codx Configuration Example

Add the following to your codx.toml:

[mcp_servers.android-i18n]
command = "node"
args = ["/path/to/android-i18n-mcp/build/index.js"]

[mcp_servers.android-i18n.env]
ANDROID_PROJECT_ROOT = "/path/to/android/project"
TRANSLATION_PROVIDER = "deepseek"
TRANSLATION_API_BASE_URL = "https://api.deepseek.com/v1"
TRANSLATION_API_KEY = "sk-xxxxxx"
TRANSLATION_MODEL = "deepseek-chat"
TRANSLATION_LANGUAGES = "zh-CN,es,fr,de,ja,ko"  # Optional: specific languages
TRANSLATOR_SOURCE_LANGUAGE = "en"  # Optional: source language (default: en)

Agent Instruction

You can configure AGENTS.md or CLAUDE.md to have the Agent automatically call MCP when strings.xml files are modified:

## Copy res update Guidelines
- Whenever a strings.xml file is modified, run android-i18n mcp to check and update copy.

Available Tools

1. translate_all_modules

Detects changes in all default strings.xml files across all modules and translates them to all supported languages.

Parameters:

  • projectRoot (optional): Android project root directory. Uses ANDROID_PROJECT_ROOT env var if not provided.

Example:

{
  "tool": "translate_all_modules",
  "arguments": {
    "projectRoot": "/path/to/android/project"
  }
}

2. translate_module

Detects changes in a specific module's default strings.xml and translates to all languages.

Parameters:

  • modulePath (required): Path to the Android module directory

Example:

{
  "tool": "translate_module",
  "arguments": {
    "modulePath": "/path/to/android/project/app"
  }
}

3. check_changes

Checks for uncommitted changes in default strings.xml files without performing translation.

Parameters:

  • projectRoot (optional): Android project root directory

Example:

{
  "tool": "check_changes",
  "arguments": {
    "projectRoot": "/path/to/android/project"
  }
}

4. check_missing_languages

Checks which language directories are missing compared to the configured TRANSLATION_LANGUAGES environment variable.

Parameters:

  • projectRoot (optional): Android project root directory

Example:

{
  "tool": "check_missing_languages",
  "arguments": {
    "projectRoot": "/path/to/android/project"
  }
}

5. create_and_translate_missing_languages

Creates missing language directories and translates the default strings.xml into them for all configured languages.

Parameters:

  • projectRoot (optional): Android project root directory

Example:

{
  "tool": "create_and_translate_missing_languages",
  "arguments": {
    "projectRoot": "/path/to/android/project"
  }
}

How It Works

  1. Change Detection: The server uses Git diff to detect which strings have been added or modified in the default values/strings.xml files since the last commit.

  2. Batch Translation: Changed strings are translated in batches to the target language using the configured AI translation API.

  3. XML Merging: Translated strings are merged into the existing language-specific strings.xml files, preserving existing translations and only updating changed ones.

  4. Module Support: The server can process multiple Android modules in a single operation, detecting all strings.xml files matching the pattern **/src/main/res/values/strings.xml.

Translation Providers

Currently supported:

  • OpenAI (including OpenAI-compatible APIs)

  • DeepSeek (automatically uses api.deepseek.com endpoint)

Planned support:

  • Anthropic Claude

  • Google Translate

DeepSeek Configuration Example:

TRANSLATION_PROVIDER=deepseek
TRANSLATION_API_KEY=your_deepseek_api_key
# Optional: defaults to deepseek-chat
TRANSLATION_MODEL=deepseek-chat
# Optional: specific languages to translate (defaults to all 28)
TRANSLATION_LANGUAGES=zh-CN,en,es,fr,de,ja,ko
# Optional: source language (defaults to 'en')
TRANSLATOR_SOURCE_LANGUAGE=en

Configuration Options

Language Selection

You can configure which languages to translate to using the TRANSLATION_LANGUAGES environment variable:

  • Translate to all 28 supported languages (default):

    # Don't set TRANSLATION_LANGUAGES or leave it empty
  • Translate to specific languages only:

    TRANSLATION_LANGUAGES=zh-CN,es,fr,de,ja,ko
  • Single language:

    TRANSLATION_LANGUAGES=zh-CN

Note: If you specify languages that are not supported, the server will:

  1. Show a warning listing the unsupported languages

  2. Display all supported languages for reference

  3. Continue with only the valid languages from your configuration

Source Language Configuration

By default, the server assumes your default values/strings.xml file uses English (en). If your project uses a different language as the default (e.g., Chinese), you need to configure the source language:

Scenario 1: Default strings.xml uses English (no configuration needed)

# Don't set TRANSLATOR_SOURCE_LANGUAGE, defaults to 'en'

Scenario 2: Default strings.xml uses Chinese

TRANSLATOR_SOURCE_LANGUAGE=zh-CN

Scenario 3: Using other languages as default

# Any supported language code
TRANSLATOR_SOURCE_LANGUAGE=es  # Spanish
TRANSLATOR_SOURCE_LANGUAGE=fr  # French
TRANSLATOR_SOURCE_LANGUAGE=ja  # Japanese
# etc...

Important Notes:

  • Correct source language configuration ensures translation quality and accuracy

  • Incorrect source language configuration may lead to translation failures or incorrect results

  • When the target language matches the source language, text will be copied directly without translation

  • Translation validation logic automatically adjusts based on the source language to avoid false untranslated warnings

Development

Run in development mode with hot reload:

npm run dev

Build the project:

npm run build

Project Structure

android-i18n-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── xmlParser.ts       # Android strings.xml parsing
│   ├── gitDiff.ts         # Git diff analysis
│   ├── translator.ts      # Translation API integration
│   └── translationManager.ts # Translation orchestration
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Notes

  • The server only translates strings that have translatable attribute not set to false

  • Deleted strings are automatically removed from translated files

  • Translation preserves Android formatting placeholders

  • All file operations are atomic - if translation fails for any language, no files are modified

License

MIT

Available Tools

5 tools
check_changesA

Check for uncommitted changes in default strings.xml files without translating

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootNoAndroid project root directory (optional)

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of disclosing behavior. 'Check' and 'without translating' clearly signal a non-mutating, read-only operation, which is useful. However, it does not mention what the tool outputs or any assumptions (e.g., git usage), so a perfect score is not warranted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence with no filler. It front-loads the action and resource and includes a useful qualifier, making every word earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no nested schemas, the description provides adequate context. It conveys the tool's scope and non-translating behavior, though it omits return-value details, which would be helpful but not essential given the low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description covers projectRoot 100%, so the description does not need to add parameter details. It does not elaborate beyond the schema, but the baseline of 3 applies because the structured info is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Check') and a clear resource ('uncommitted changes in default strings.xml files'). The qualifier 'without translating' distinguishes it from the sibling translation tools, making its purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'without translating' implies this is a pre-translation check, but the description does not explicitly state when to use it versus alternatives like check_missing_languages or translate_all_modules. There is no direct 'use this instead of X' guidance, only an implicit context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_missing_languagesA

Check which language directories are missing compared to configured TRANSLATION_LANGUAGES

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootNoAndroid project root directory (optional)

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It indicates a read-only 'check' operation but does not describe the output format, where TRANSLATION_LANGUAGES is configured, or how missing languages are reported. While the action is clearly non-destructive, significant behavioral details are unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that front-loads the core purpose. Every word contributes meaning, with no unnecessary elaboration or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description provides the essential context: what operation is performed and what is compared. It does not explicitly relate to sibling tools, but the simplicity of the operation means the description is largely complete, save for minor details like the source of TRANSLATION_LANGUAGES.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides a description for the single optional parameter projectRoot, achieving 100% schema coverage. The tool description adds no additional parameter context, so the baseline of 3 applies; the schema sufficiently explains the parameter's meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's specific function: checking which language directories are missing relative to TRANSLATION_LANGUAGES. The verb 'check' combined with the resource 'missing language directories' and the comparison against a configured list distinguishes it from the sibling tools, which focus on translating or checking changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the tool's purpose—it is for identifying missing language directories—but there is no explicit guidance on when to use it versus alternatives like check_changes or create_and_translate_missing_languages. No exclusions or prerequisites are mentioned, so the agent must infer the appropriate context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_and_translate_missing_languagesA

Create missing language directories and translate default strings.xml into them

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootNoAndroid project root directory (optional)

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It discloses the core mutations (creating directories and translating strings.xml) but does not mention potential side effects, such as whether existing files are overwritten, whether network calls are made, or what the return value is.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that contains all necessary information without extraneous detail. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool shape (one optional parameter, no output schema) the description is adequate for basic invocation, but it omits explicit guidance on when to use this tool relative to sibling tools and does not mention return values. It is complete enough for a simple scenario but leaves some ambiguity when compared to translate_module.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter projectRoot is fully described in the schema as an optional Android project root directory. The tool description adds no parameter-specific information beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates missing language directories and translates the default strings.xml into them, using specific verbs and resources. It distinguishes from siblings by focusing on missing languages and the default strings.xml source.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for missing languages through its name and phrasing, but does not explicitly state when to choose it over translate_all_modules or translate_module. No exclusions or alternative tools are mentioned, leaving the agent to infer the appropriate context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

translate_all_modulesA

Detect changes in all default strings.xml files using git diff and translate them to all supported languages

ParametersJSON Schema
NameRequiredDescriptionDefault
projectRootNoAndroid project root directory (optional, uses ANDROID_PROJECT_ROOT env var if not provided)

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It reveals the use of git diff for detection but does not mention that translation likely modifies files, whether changes are committed, or the risk of unintended modifications. The description omits key side effects and prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the main action and includes the method (git diff) and scope (all supported languages). Every word contributes to understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a relatively simple tool but lacks details on output, prerequisites (e.g., existing git repo, clean working tree), and side effects of translation. With no output schema and no annotations, more context would be needed for an agent to fully anticipate tool behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage with a description for projectRoot, so the baseline is 3. The tool description adds no additional semantic details about the parameter beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: detect changes in all default strings.xml files via git diff and translate them to all supported languages. It specifies a concrete resource (all default strings.xml files) and distinguishes from the sibling translate_module by covering all modules.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context: for batch detection and translation across all modules. However, it does not explicitly mention alternatives like using translate_module for a single module or check_changes to only detect changes, nor does it state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

translate_moduleA

Detect changes in a specific module's default strings.xml using git diff and translate to all languages

ParametersJSON Schema
NameRequiredDescriptionDefault
modulePathYesPath to the Android module directory

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses use of git diff and that translation targets all languages, but does not mention side effects like file modifications, commit behavior, or prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single direct sentence with no fluff, front-loaded with the action and resource; every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema, the description adequately conveys the main behavior. It could mention side effects or error conditions, but given the simplicity it is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers modulePath fully, but the description adds meaning by explaining that the module's default strings.xml is the target and that git diff is used, clarifying the purpose beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Detect... and translate') with a precise resource ('specific module's default strings.xml'), clearly distinguishing it from sibling 'translate_all_modules'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context implies this is for a single module versus 'translate_all_modules', but it does not explicitly state when not to use it or compare with 'check_missing_languages' or 'create_and_translate_missing_languages'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.0
    • First observedcheck_changes
    • First observedcheck_missing_languages
    • First observedcreate_and_translate_missing_languages
    • First observedtranslate_all_modules
    • First observedtranslate_module

TDQS

A4/5.0

Scored across 5 tools

Disambiguation4/5

Tools are mostly distinct: translate_all_modules and translate_module differ by scope (all vs specific module), while check_changes and check_missing_languages have clearly separate purposes. The create_and_translate_missing_languages tool also stands apart by focusing on directory creation plus translation. Only minor overlap exists between the two translate tools.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: translate_all_modules, translate_module, check_changes, check_missing_languages, create_and_translate_missing_languages. The pattern is predictable and uniform.

Tool Count5/5

5 tools is well-scoped for an i18n server. The set covers translation, change detection, and language directory management without excessive overlap or missing essential actions.

Completeness4/5

The toolset covers the core workflows: detecting changes, translating, checking missing languages, and creating missing language directories. A minor gap is the lack of a tool to explicitly list configured languages or operate on a single language-specific translation, but these are not critical for the main purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers