translate_text

Instructions

支持 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 的原始响应数据

Implementation Reference

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

  The main tool handler function for 'translate_text', decorated with @mcp.tool(). Handles input validation via Annotated types (schema), normalizes language codes, calls Niutrans API via helper, and formats the response.

  @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:508-530 (helper)

  Helper function that makes the HTTP POST request to the Niutrans API, handles errors, and returns the parsed JSON 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-559 (helper)

  Helper function to normalize and validate language codes for source and target, using aliases, synonyms, and fuzzy matching.

  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 资源提供的列表后重新选择。"
      )