HY Translation Skill

This skill leverages the HuanYuan translation model to provide high-quality machine translation with advanced instruction-following capabilities. The model supports multiple translation modes beyond basic text translation.

When to Use

• Translating text between any language pair
• Translating with specific terminology requirements (glossary)
• Translating with style constraints (formal, colloquial, academic, etc.)
• Translating structured data (JSON, HTML, Markdown) while preserving format
• Translating text with delimiters that must be preserved
• Translating with contextual background information

API Backends

Backend descriptions:

• tencent_cloud: Uses the Hy Translation API provided by Tencent Cloud. The endpoint URL has a built-in default (https://api.hunyuan.cloud.tencent.com/v1/chat/completions) — the user does not need to provide it. However, the user may optionally supply a different URL, which will be stored in memory and used going forward. A model name and API key are always required. Suitable for users who have access to Tencent Cloud services.
• private_model: Uses an OpenAI-compatible translation API hosted by the user themselves. The endpoint URL, model name, and API key must all be provided by the user. Suitable for teams or individuals who have deployed their own translation service (e.g. an internal service).

Backend Setup Guide

🌐 Tencent Cloud Backend (tencent_cloud)

To get started with the Tencent Cloud backend, visit the model detail page below. It provides the model overview, pricing information, a code sample (including the model name), and a link to apply for an API key:

👉 https://console.cloud.tencent.com/tokenhub/models/detail?modelId=hy-mt2-pro

You will need to create a Tencent Cloud account if you don't already have one. Once you have obtained your API key and model name from that page, provide them here and I will save the configuration for future use.

🏠 Private Model Backend (private_model)

To get started with a self-hosted model, download the model files and follow the deployment instructions from the HuggingFace collection page below:

👉 https://huggingface.co/collections/tencent/hy-mt2

Important: The deployed model service must expose an OpenAI-compatible interface (/v1/chat/completions). Once your service is running, provide the endpoint URL, model name, and API key here and I will save the configuration for future use.

Memory keys (used to persist credentials across sessions):

Active backend persistence: once the user provides or confirms a backend, it becomes the active backend for the entire session and subsequent sessions. Store it in memory as active_translation_backend. Only switch when the user explicitly requests a different backend.

Workflow

Step 1 — Validate target language

Check whether the requested language is in the 38 supported languages. See supported-languages.md for the full list. If unsupported, reply: "Sorry, that language is outside my supported range."

Step 2 — Determine active backend and credentials

Follow this decision tree every time a translation request arrives:

1. Check conversation history and memory for the most recently used backend:

   • Look at recent messages in the current conversation first.
   • If not found in conversation, check memory key active_translation_backend.
   • If found, use that backend — do not ask the user again.

2. If no prior backend is found in history or memory:

   • Ask the user which backend to use: Tencent Cloud or Private Model.
   • Write the chosen backend to memory: active_translation_backend = tencent_cloud | private_model.

3. Only switch the active backend when the user explicitly says so (e.g. "换成私有模型", "switch to private model", "use tencent cloud instead"). After switching, update active_translation_backend in memory.

4. Credential resolution — check memory for the active backend's credentials:

   For tencent_cloud — need: model name + API key; URL is optional

   • For the URL: check memory for tencent_cloud_url; if present use it, otherwise use the default https://api.hunyuan.cloud.tencent.com/v1/chat/completions. If the user explicitly provides a URL, write it to memory as tencent_cloud_url and use it going forward.
   • If tencent_cloud_model or tencent_cloud_api_key is missing from memory, ask the user to provide them.
   • Once provided, write to memory (tencent_cloud_model, tencent_cloud_api_key).

   For private_model — need: endpoint URL + model name + API key

   • If any of private_model_url, private_model_name, private_model_api_key is missing from memory, ask the user to provide all three at once.
   • Once provided, write to memory (private_model_url, private_model_name, private_model_api_key).

   Never ask for credentials that are already stored in memory.

Step 3 — Build and execute the translation command

Locate the script first. Before running any command, resolve the actual path of hy_translate.py by executing:

HY_SCRIPT=$(find ~ -name "hy_translate.py" -path "*/hy-mt2-translator/scripts/*" 2>/dev/null | head -1)
echo "$HY_SCRIPT"

Use the resolved $HY_SCRIPT value in all subsequent commands. If the file is not found, report an error and stop.

Parameter substitution rules (apply to all commands below):

Determine the translation mode from translation-modes.md, then run the matching command. Fill in all placeholders with real values before executing.

3a. Basic translation (default)

python3 "$HY_SCRIPT" \
  --text "\x3Csource text here>" \
  --target-lang "\x3Clang abbr or Chinese name, e.g. en / 英语>" \
  --backend \x3Cactive_backend> \
  --url "\x3Cprivate_model_url from memory>" \
  --model "\x3Cmodel from memory>" \
  --api-key "\x3Capi_key from memory>"

3b. Terminology-constrained translation

python3 "$HY_SCRIPT" \
  --text "\x3Csource text here>" \
  --target-lang "\x3Clang abbr or Chinese name, e.g. en / 英语>" \
  --backend \x3Cactive_backend> \
  --url "\x3Cprivate_model_url from memory>" \
  --model "\x3Cmodel from memory>" \
  --api-key "\x3Capi_key from memory>" \
  --terminology $'\x3Csrc1>翻译成\x3Ctgt1>\
\x3Csrc2>翻译成\x3Ctgt2>'

--terminology is a raw string embedded directly into the prompt. Use \ to separate multiple term pairs, e.g.: $'人工智能翻译成Artificial Intelligence\ 机器学习翻译成Machine Learning'

3c. Style-controlled translation

python3 "$HY_SCRIPT" \
  --text "\x3Csource text here>" \
  --target-lang "\x3Clang abbr or Chinese name, e.g. en / 英语>" \
  --backend \x3Cactive_backend> \
  --url "\x3Cprivate_model_url from memory>" \
  --model "\x3Cmodel from memory>" \
  --api-key "\x3Capi_key from memory>" \
  --style "\x3Cstyle description, e.g. 学术论文严谨风格>"

3d. Delimiter-preserving translation

python3 "$HY_SCRIPT" \
  --text "\x3Ctext with delimiters, e.g. Hello@@World>" \
  --target-lang "\x3Clang abbr or Chinese name, e.g. en / 英语>" \
  --backend \x3Cactive_backend> \
  --url "\x3Cprivate_model_url from memory>" \
  --model "\x3Cmodel from memory>" \
  --api-key "\x3Capi_key from memory>" \
  --preserve-delimiters

3e. Structured-data translation (JSON / HTML / XML / YAML / Markdown)

python3 "$HY_SCRIPT" \
  --text '\x3Cstructured data, e.g. {"name":"John","greeting":"Hello"}>' \
  --target-lang "\x3Clang abbr or Chinese name, e.g. en / 英语>" \
  --backend \x3Cactive_backend> \
  --url "\x3Cprivate_model_url from memory>" \
  --model "\x3Cmodel from memory>" \
  --api-key "\x3Capi_key from memory>" \
  --format-type "\x3CJSON|HTML|XML|YAML|Markdown>"

3f. Context-aware translation

python3 "$HY_SCRIPT" \
  --text "\x3Csource text here>" \
  --target-lang "\x3Clang abbr or Chinese name, e.g. en / 英语>" \
  --backend \x3Cactive_backend> \
  --url "\x3Cprivate_model_url from memory>" \
  --model "\x3Cmodel from memory>" \
  --api-key "\x3Capi_key from memory>" \
  --context "\x3Cbackground description, e.g. 医学检测报告场景>"

3g. Multi-line / special-character text

Write the source text to a temp file to avoid shell-escaping issues, then use --input-file instead of --text:

cat > /tmp/hy_src.txt \x3C\x3C 'EOF'
\x3Cpaste source text here>
EOF

python3 "$HY_SCRIPT" \
  --input-file /tmp/hy_src.txt \
  --target-lang "\x3Clang abbr or Chinese name, e.g. en / 英语>" \
  --backend \x3Cactive_backend> \
  --url "\x3Cprivate_model_url from memory>" \
  --model "\x3Cmodel from memory>" \
  --api-key "\x3Capi_key from memory>"

Mode-specific flags (e.g. --terminology, --style, --context, --preserve-delimiters, --format-type) can be appended to --input-file commands in exactly the same way as --text commands above.

3h. Batch JSONL translation

Input JSONL format: each line must contain a text (or source_text) field. Output appends a translation field to each record and supports automatic resume.

python3 "$HY_SCRIPT" \
  --input "\x3Cpath/to/input.jsonl>" \
  --output "\x3Cpath/to/output.jsonl>" \
  --target-lang "\x3Clang abbr or Chinese name, e.g. en / 英语>" \
  --workers 30 \
  --backend \x3Cactive_backend> \
  --url "\x3Cprivate_model_url from memory>" \
  --model "\x3Cmodel from memory>" \
  --api-key "\x3Capi_key from memory>"

Step 4 — Return the result

• Single translation: display the translated text directly.
• Batch job: report success/failure counts and output file path.
• Never expose the raw API key in the reply.

Key Notes

• --target-lang accepts both abbreviation (en) or Chinese name (英语)
• Translation mode is auto-detected from flags; --mode is not needed
• Batch output resumes automatically if the output file already exists
• When active backend is tencent_cloud, --url uses the value from memory (tencent_cloud_url) if set, otherwise the script falls back to the built-in default URL automatically