fabricatio-translate

LLM-powered text translation capability for Fabricatio agents. Supports single and batch translation with chunked processing for large texts.

Installation

pip install fabricatio[translate]
# or
uv pip install fabricatio[translate]

Architecture

The package provides a single capability mixin (Translate) that layers into a Fabricatio Role:

Usage

Mix Translate into a Role to get translation methods:

import asyncio
from fabricatio import Role
from fabricatio_translate.capabilities.translate import Translate

class TranslatorRole(Role, Translate):
    """Role with translation capability."""

async def main() -> None:
    role = TranslatorRole(name="translator")

    # Single text
    result = await role.translate("Hello, world.", target_language="fr")
    print(result)  # "Bonjour, le monde."

    # Batch translation
    results = await role.translate(["Hello", "Goodbye"], target_language="de")
    print(results)  # ["Hallo", "Auf Wiedersehen"]

    # Chunked translation for long text (splits by word count)
    long_text = "A very long paragraph..." * 1000
    result = await role.translate_chunked(long_text, target_language="ja", chunk_size=4000)

    # With custom specification
    result = await role.translate(
        "The quick brown fox",
        target_language="zh",
        specification="Use formal register. Preserve animal names.",
    )

asyncio.run(main())

Fallback behavior

If an individual translation fails, the source text is preserved in the output list rather than raising an exception. The utility fill_empty handles this gap-filling:

from fabricatio_translate.capabilities.translate import fill_empty

result = fill_empty(["a", "b", "c"], ["translated_a", None, None])
# result == ["translated_a", "b", "c"]

API Reference

Translate capability

Both methods accept a specification string for style, tone, or terminology instructions passed to the LLM template.

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.translate] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.translate] in pyproject.toml, or via FABRICATIO_EXT__TRANSLATE__<FIELD_UPPER> environment variables.

[ext.translate]
translate_template = "built-in/translate"

Access at runtime: from fabricatio_translate.config import translate_config.

Kwargs types

License

MIT — see the LICENSE file.