Translation Plugin¶

The translation plugin provides the translate_text tool, which uses an LLM agent to translate text or file contents into a target language. It is designed to preserve structural elements like URLs, code blocks, and markup while maintaining security through structural isolation.

Quick start¶

Ensure your settings declare an LLM and point the tool at it:

# ~/.config/aifred-tk/settings.yml
llms:
  my-llm:
    provider: openai
    model: gpt-4o-mini

tools:
  translate_text:
    llm:
      type: ref
      ref: my-llm

Then invoke the tool:

aifred-tk translate_text --text "Hello, how are you?" --target-language "Spanish"

Configuration¶

LLM setting¶

The tools.translate_text.llm key is required. It accepts a reference to a named LLM or an inline definition. See LLMs for the full format.

# Reference a named LLM
tools:
  translate_text:
    llm:
      type: ref
      ref: my-llm

# Or define inline
tools:
  translate_text:
    llm:
      type: custom
      provider: ollama
      model: gemma4:e4b

Enabling and disabling¶

The tool respects the standard enabled flag:

tools:
  translate_text:
    enabled: false

Usage¶

CLI¶

aifred-tk translate_text [--text TEXT] [--file-path PATH] --target-language LANG [--context TEXT]

Option	Description
`--text TEXT`	Inline text to translate (max 100,000 characters). Mutually exclusive with `file-path`.
`--file-path PATH`	Path to a UTF-8 text file to translate. Mutually exclusive with `text`.
`--target-language LANG`	Name of the target language (e.g., "Spanish", "Japanese"). Required.
`--context TEXT`	Optional hint for terminology or style (e.g., "legal", "informal").

MCP¶

The tool is registered automatically when the MCP server starts. Invoke it as aifred_translate_text with the required target_language and either text or file_path.

Output¶

Success (`status: ok`)¶

{
  "status": "ok",
  "translation": "Hola, ¿cómo estás?"
}

Error (`status: error`)¶

{"status": "error", "message": "File exceeds the 1 MB size limit (2097152 bytes)."}

{"status": "error", "message": "Provide either 'text' or 'file_path', not both."}

Preservation & Security¶

Preservation Rules¶

By default, the translation agent is instructed to preserve the following elements unchanged:

URLs and hyperlinks
File system paths
Markup tags (HTML, XML, Markdown)
Technology and brand names (e.g., Python, Docker, GitHub)
Code spans and blocks (text in backticks or code fences)
Placeholder tokens (e.g., {name}, %s)

Security Constraints¶

XML Isolation — The source text is wrapped in <text_to_translate> markers. The agent is strictly instructed to treat everything inside these tags as passive data and to ignore any directives (like "ignore previous instructions") found within.
Air-gapped Agent — The agent has no access to external APIs, local files (other than the provided source), or shell commands.
Literal Translation — Injection attempts are translated literally rather than followed.