MCP Translation Text

Instructions

Implementation Reference

• src/translation_server.py:562-611 (handler)

  The main handler function for the 'translate_text' tool. It validates input languages, constructs the API payload, calls the Niutrans translation API via _call_niutrans helper, and returns a structured response with the translation.
  @mcp.tool() def translate_text( text: Annotated[str, Field(description="待翻译的原文文本，可以是任意长度的字符串。")], source: Annotated[str, Field(description='源语言代码或常见别名（例如 "zh"、"中文"、"chinese"）。')], target: Annotated[str, Field(description='目标语言代码或常见别名（例如 "en"、"英文"、"english"）。')], ) -> Dict[str, Any]: """使用小牛翻译 API 将文本从 source 语种翻译到 target 语种。 支持 450+ 种语言代码，并可自动处理常见别名。返回结构包含译文和 API 原始响应。 Args: text (str): 待翻译的原文文本，可以是任意长度的字符串。 source (str): 源语言代码或常见别名（例如 "zh"、"中文"、"chinese"）。 target (str): 目标语言代码或常见别名（例如 "en"、"英文"、"english"）。 Returns: Dict[str, Any]: 包含以下字段的字典： - source: 标准化后的源语言代码 - target: 标准化后的目标语言代码 - original_text: 原文 - translated_text: 译文 - raw: 小牛翻译 API 的原始响应数据 """ api_key = os.getenv("NIUTRANS_API_KEY") if not api_key: raise RuntimeError("缺少环境变量 NIUTRANS_API_KEY") source_code = _ensure_language_code("source", source) target_code = _ensure_language_code("target", target) payload: Dict[str, Any] = { "apikey": api_key, "from": source_code, "to": target_code, "src_text": text, } data = _call_niutrans(payload) translated = data.get("tgt_text") or data.get("target_text") if translated is None: raise RuntimeError(f"小牛翻译接口未返回译文: {data}") return { "source": source_code, "target": target_code, "original_text": text, "translated_text": translated, "raw": data, }
• src/translation_server.py:563-567 (schema)

  Pydantic schema for tool inputs using Annotated types and Field descriptions for text, source language, and target language.
  def translate_text( text: Annotated[str, Field(description="待翻译的原文文本，可以是任意长度的字符串。")], source: Annotated[str, Field(description='源语言代码或常见别名（例如 "zh"、"中文"、"chinese"）。')], target: Annotated[str, Field(description='目标语言代码或常见别名（例如 "en"、"英文"、"english"）。')], ) -> Dict[str, Any]:
• src/translation_server.py:562-562 (registration)

  The @mcp.tool() decorator registers the translate_text function as an MCP tool.
  @mcp.tool()
• src/translation_server.py:508-531 (helper)

  Helper function that makes the HTTP POST request to the Niutrans API, handles errors, and returns the parsed response.
  def _call_niutrans(payload: Dict[str, Any]) -> Dict[str, Any]: api_url = os.getenv("NIUTRANS_API_URL", DEFAULT_NIUTRANS_API_URL) try: response = requests.post(api_url, data=payload, timeout=10) except requests.RequestException as exc: raise RuntimeError(f"调用小牛翻译接口失败: {exc}") from exc if response.status_code != 200: raise RuntimeError( f"小牛翻译接口返回非 200 状态码 {response.status_code}: {response.text}" ) try: data: Dict[str, Any] = response.json() except ValueError as exc: raise RuntimeError("小牛翻译接口返回非 JSON 内容") from exc error_code = data.get("error_code") or data.get("errorCode") if error_code not in (None, "0", 0): message = data.get("error_msg") or data.get("errorMessage") or "Unknown error" raise RuntimeError(f"小牛翻译接口报错 {error_code}: {message}") return data
• src/translation_server.py:533-560 (helper)

  Helper function to normalize and validate source/target language codes using synonyms and aliases.
  def _ensure_language_code(label: str, value: str) -> str: if not value: raise RuntimeError(f"缺少 {label} 语言代码") raw = value.strip() if raw in LANGUAGE_CODES: return raw normalized = _normalize_alias(raw) if normalized in LANGUAGE_CODES: return normalized alias_code = LANGUAGE_SYNONYMS.get(normalized) or LANGUAGE_SYNONYMS.get( normalized.replace(" ", "") ) if alias_code: return alias_code normalized_lower = raw.lower() for code in LANGUAGE_CODES: if code.lower() == normalized_lower: return code raise RuntimeError( f"不支持的 {label} 语言代码: {value}。请参考 language-catalog 资源提供的列表后重新选择。" )