Skip to main content
Glama
cht-codeini

i18n-file-replace-mcp

by cht-codeini

i18n 文件替换

replace_file

Replaces hardcoded text in source files with i18n resource keys via the i18n platform API, returning generated keys and optional machine translations.

Instructions

调用 i18n 平台(https://i18n.codeini.com)文件替换 API,将普通代码文件转换为支持多语言的代码文件。返回替换后的 content、生成的 generatedKeys 与 keyCount。需配置环境变量 I18N_API_KEY(平台 API Key)。 必须提供 configJson 或 profileName 之一。 提供 translateTo(目标语言数组,如 ["en"])且带 resourceSet 时,替换后会把每个 key 机翻到目标语言并一并写入资源库(返回 translatedCount)。

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
contentYes要替换的文件完整内容
fileNameYes被替换文件的名称,用于生成 key(如 Home.vue;带目录前缀如 pages/member/list.vue 时 key 会包含目录信息)
configJsonNo替换配置 JSON(I18nReplaceConfigDto,与 profileName 二选一,优先级更高)
profileNameNo平台上已保存的配置名(与 configJson 二选一)
resourceSetNo非空时将生成的 key 写入该资源集(写入平台数据库,LocaleId=zh)
translateToNo配合 resourceSet 使用:写入源语言(zh)后,把每个生成的 key 机翻到这些目标语言(如 ["en"] 或 ["en","ja"]),译文以相同 id 写入同一资源集。需同时提供 resourceSet
resourceSetByDirNo为 true 且提供了 resourceSet 时,实际资源集为 <resourceSet>.<fileName 的第一级目录>(与 CLI --resource-set-by-dir 一致,如 portal.member);fileName 无目录前缀时退化为 resourceSet 本身
translateProviderNo机翻提供方(缺省用平台默认提供方,可用环境变量 I18N_TRANSLATE_PROVIDER)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.2.1

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description carries full burden. It discloses side effects (writing generated keys to the platform database when resourceSet is provided, machine translation to target languages), return values (content, generatedKeys, keyCount, translatedCount), and the required environment variable. This is highly transparent about behavioral outcomes.

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

Conciseness4/5

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

The description is a compact set of sentences that front-loads the primary purpose and returns, then covers constraints and optional behavior. It is dense but well-organized, with each sentence adding essential information. Slight denseness prevents a perfect score.

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?

Given 8 parameters and no output schema, the description covers the core workflow, required conditions, side effects, and return values. It does not detail the exact structure of configJson, but that is beyond the scope of a tool description; the schema already identifies it as a DTO. The description is sufficiently complete for an agent to call the tool correctly.

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?

Although schema description coverage is 100%, the description adds critical semantics beyond the schema: the mutual exclusivity of configJson and profileName (with priority), the condition that translateTo requires resourceSet, and the explanation of resourceSetByDir behavior. These additions help the agent avoid invalid calls.

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 converts ordinary code files into multi-language capable code files via the i18n platform API, and lists the returned values (content, generatedKeys, keyCount). It distinguishes itself from siblings like preview_replace (which previews) and the listing tools by focusing on the actual replacement operation.

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?

It provides explicit conditions: must supply configJson or profileName, and translateTo requires resourceSet. It also mentions the prerequisite of setting I18N_API_KEY. However, it doesn't explicitly state when to prefer this over preview_replace or when not to use it, though the action is clearly the primary mutation tool among siblings.

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