Translation Configurations

The Translation Configurations page in PinionAI Studio allows you to manage real-time, multi-language translation for your AI agents. PinionAI utilizes an English-core architecture: agents maintain their internal reasoning, prompts, intent classification, tools, and RAG knowledge base in English, while dynamically communicating with users in their native languages.

When a user interacts with an agent in another language, PinionAI automatically translates incoming messages into English for internal processing, and translates the agent's responses back into the user's preferred language before delivery.

Permissions & Prerequisites

Access to the Translation Configurations page and its underlying operations is controlled by user permissions and system context:

Account & Agent Context: You must select an active Account from the sidebar. You can also filter configurations or associate new ones with a selected Agent.
Required Roles: Users must have one of the following permissions:
owner
admin
editor
data
translations (explicit page-level permission)
watchover (super-admin / global monitor)

Page Overview

The page is organized into two primary sections:

Translation Builder / AI Architect: For creating new translation configurations manually or with the help of the AI configuration assistant.
Translation Configuration List: An expandable, filterable list of all translation configurations associated with the selected account or agent, with inline actions to edit, duplicate, export, or delete them.

AI Translation Architect

PinionAI Studio includes an AI Translation Architect assistant to streamline setting up models, connectors, endpoints, and language mappings.

Click the AI Suggest Configuration button under the New Translation section.
A dialog will open asking you to describe your translation requirements (e.g., "Set up bidirectional Spanish translation using Gemini 3.5 Flash with low temperature" or "Configure DeepL for outbound German customer responses").
Click Generate Suggested Configuration. The AI will automatically architect a complete configuration including recommended provider, direction, model name, language code, temperature, and protocols.
Review the suggested fields and click Apply Suggested Configuration to populate the creation form, or click Cancel to discard.

Adding a New Translation Configuration

Expand the New Translation section to configure a new translation profile.

1. General & Core Settings

Direction: Controls the translation flow relative to your English core backend:
inbound: Translates foreign user input into English before intent matching, prompt execution, tools, and RAG.
outbound: Translates the agent's final English response back into the user's foreign language.
bidirectional: Handles both inbound and outbound translation for this language code in a single configuration row.
Configuration Name: A unique, descriptive identifier for this profile (e.g., spanish_bidirectional_google or outbound_german_deepl).
Active: A toggle to enable or disable the configuration.
Provider: Choose from supported translation engines:
google: Google Cloud Translation or Gemini-powered dynamic translation (e.g., gemini-2.5-flash).
openai: OpenAI GPT models (e.g., gpt-4o-mini).
deepl: DeepL Translation API.
anthropic: Anthropic Claude models (e.g., claude-3-5-haiku-20241022).
huggingface: Hosted or self-hosted translation endpoints.
Connector: Select an optional Connector that securely supplies API keys or service account credentials without hardcoding secrets.
Agent(s): Multi-select of agents permitted to use this translation configuration. Select All to make it globally available within the account.

2. Language & Model Settings

Language Code: The non-English language code this row handles (e.g., es for Spanish, fr for French, de for German, ja for Japanese, or any for a catch-all fallback configuration).
Model Name: The specific model identifier used for translation (e.g., gemini-2.5-flash, gpt-4o-mini, claude-3-5-haiku-20241022, v2, or default).
Temperature (LLM): Creative temperature for LLM-based providers (must be between 0.0 and 2.0; values between 0.0 and 0.3 are recommended for consistent, faithful translations).

3. Service Endpoint & Connection (Optional)

Endpoint URL: Custom base URL or API route (e.g., https://api.deepl.com/v2/translate or a self-hosted translation service URL). Leave blank to use provider defaults.
Port (optional): Specific port number (between 1 and 65535) if not part of the endpoint URL.
Protocol: Communication protocol (https, http, grpc).
Description: Optional documentation or notes describing the configuration.

Service Configuration Guide & Examples

1. Bidirectional Spanish via Google Gemini

Fast, context-aware translation with nuanced phrasing and low latency.

Name: spanish_bidirectional_google
Direction: bidirectional
Language Code: es
Provider: google
Model: gemini-2.5-flash
Temperature: 0.0
Connector: Google Cloud / Gemini Connector

2. Inbound Multilingual Fallback via OpenAI

A universal catch-all for any incoming foreign language.

Name: inbound_multilingual_openai
Direction: inbound
Language Code: any
Provider: openai
Model: gpt-4o-mini
Temperature: 0.1
Connector: OpenAI API Key Connector

3. Outbound German Translation via DeepL

High-accuracy formal/informal European language translation using DeepL's dedicated API.

Name: outbound_german_deepl
Direction: outbound
Language Code: de
Provider: deepl
Model: v2
Endpoint: https://api.deepl.com/v2/translate
Connector: DeepL API Key Connector

4. French Translation via Anthropic Claude

Leverages Claude 3.5 Haiku for nuanced localization.

Name: french_bidirectional_claude
Direction: bidirectional
Language Code: fr
Provider: anthropic
Model: claude-3-5-haiku-20241022
Temperature: 0.0
Connector: Anthropic API Key Connector

Runtime Client & Agent Usage (`pinionai/client.py`)

At runtime, translation is invoked seamlessly when processing user turns.

1. Specifying the Language

Callers pass the user's preferred language code into process_user_input:

# Direct language parameter
response_text, file_type = await client.process_user_input(
    user_input="¿Cuál es el horario de atención?",
    language="es"
)

# Alternatively, set in session variables
client.var["user_language"] = "es"
response_text, file_type = await client.process_user_input(
    user_input="¿Cuál es el horario de atención?"
)

2. Execution Flow

Inbound Resolution:
If language is non-English, client searches its translation configurations for a matching inbound or bidirectional rule (exact match e.g. es, prefix match e.g. es-MX $\to$ es, or fallback any).
The original input is preserved in client.var["raw_user_input"].
The translated text is stored in client.var["translated_user_input"] and becomes the active user_input.
Core Agent Processing:
The agent executes all intent matching, prompt engineering, tools, and RAG knowledge retrieval in English.
Outbound Resolution:
Before returning the final response, client searches for an outbound or bidirectional configuration matching the language.
The original English response is preserved in client.var["english_response"].
The response is translated back into the user's language and returned to the caller.

3. Programmatic Helper

You can also translate arbitrary text directly via the client instance:

translated = await client.translate_text(
    text="Your appointment has been confirmed for 3:00 PM.",
    target_language="es",
    source_language="en",
    config_name="spanish_bidirectional_google"  # Optional
)

Managing Configurations

Editing: Click Edit on any configuration card to adjust models, endpoints, or language codes.
Duplicating: Click Duplicate to clone an existing configuration as a template for a new language.
Exporting & Importing:
Individual configurations can be exported directly to JSON via the Export button.
JSON configurations can be re-imported in the Import Translation expander or bulk-imported via the Import page (30_Import.py).
Deleting: Remove inactive configurations directly from the edit view.