Translation

Babelon uses AI to generate translation candidates that humans can then review and approve. This page explains how the translation pipeline works, how to configure providers, and how Babelon handles ICU MessageFormat and protected terms.

AI providers

Babelon supports three translation providers:

Provider	Default model	Best for
Anthropic Claude	claude-3-5-sonnet-20241022	High-quality, context-aware translations
OpenAI	gpt-4o	Fast, reliable translations
Google Translate	N/A (neural MT)	Cost-effective bulk translation

Provider resolution

When a translation job runs, Babelon resolves the provider in this order:

1. Custom provider -- If you have configured your own API key in Settings, that provider is used.
2. Tenant settings -- If a provider is selected in your organization settings (without a custom key), the platform's shared API key is used.
3. Platform default -- Falls back to the platform's default provider.

Configuring a provider

To set up your own API key:

1. Go to Settings in the sidebar.
2. Under Translation Provider, select "Custom provider."
3. Choose your provider: Anthropic, OpenAI, or Google Translate.
4. Enter your API key. For Google Translate, you also need your GCP project ID.
5. Optionally select a specific model.
6. Save.

Your API key is encrypted with AES-256-GCM before being stored. It is never exposed through the API or the UI after initial entry.

TIP

You can switch providers at any time. Each new translation job will use whatever provider is configured when the job runs.

ICU MessageFormat

Babelon has first-class support for ICU MessageFormat, the industry standard for representing translatable strings with dynamic content.

What is ICU MessageFormat?

ICU MessageFormat lets you express placeholders, plurals, gender selects, and number/date formatting in a single string:

Hello, {name}!

{count, plural,
  one {You have # new message}
  other {You have # new messages}
}

{gender, select,
  male {He liked your post}
  female {She liked your post}
  other {They liked your post}
}

Sale ends {date, date, long}

How Babelon preserves placeholders

Babelon validates ICU syntax at multiple points in the pipeline:

1. On upload -- The CLI validates ICU syntax before sending messages to the server.
2. On translation -- After the AI generates a translation, Babelon validates that all placeholders from the source text appear in the output and that braces are balanced.
3. On manual edit -- The web editor validates ICU syntax when you save a translation.

If a translation fails ICU validation, the job is marked as failed rather than saving a broken translation. This prevents corrupted placeholders from reaching your application.

ICU preservation by provider

Each provider handles ICU differently:

• Claude and OpenAI -- The translation prompt explicitly instructs the model to preserve all {placeholder} variables, plural forms, and select clauses. Post-translation validation confirms compliance.
• Google Translate -- ICU placeholders are preprocessed into XML tags before being sent to the API, then reconstructed afterward. This prevents the neural model from altering placeholder syntax.

Supported ICU features

Feature	Syntax example
Simple placeholder	{name}
Plural	{count, plural, one {# item} other {# items}}
Select	{gender, select, male {He} female {She} other {They}}
Select ordinal	{pos, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}
Number format	{amount, number, currency}
Date format	{date, date, short}
Nested messages	Plurals and selects can contain other ICU expressions
Escaping	'' for a literal quote, '{text}' for literal braces

Protected terms

Protected terms are brand names, acronyms, or domain-specific words that should never be translated. For example:

• Product names: "Babelon", "iPhone", "Kubernetes"
• Acronyms: "API", "SDK", "URL"
• Technical terms: "webhook", "OAuth"

Setting up protected terms

1. Go to Settings in the sidebar.
2. Find the Protected Terms section.
3. Add each term that should remain untranslated.
4. Save.

Protected terms are included in the AI translation prompt with explicit instructions to keep them in their original form. They are enforced during both AI translation and manual editing in the web dashboard.

Translation statuses

Every translation has one of three statuses:

Status	Meaning
Pending	Generated by AI or imported, awaiting human review
Approved	Reviewed and confirmed, eligible for export
Rejected	Flagged as incorrect, needs retranslation or manual editing

Translation sources

Translations are also tagged by source:

Source	Description
ai	Generated by an AI provider
human	Written or edited manually in the web editor
imported	Uploaded via the CLI

Review workflow

The default workflow for AI-generated translations is:

1. AI generates a candidate -- The translation is saved with pending status.
2. Human reviews -- A team member checks the translation on the Review page or in the Translation Editor.
3. Approve or reject -- Approved translations become available for export. Rejected translations can be retranslated or manually corrected.

Auto-approve

If you trust your AI provider and want to skip the review step, enable Auto-approve AI translations in Settings. When enabled, AI translations are saved with approved status immediately.

WARNING

Auto-approve is convenient but means AI output goes directly into your exports without human review. Consider using it only for less critical content or well-tested language pairs.

Bulk review

The Review page supports bulk operations. Select multiple translations using the checkboxes, then approve or reject them all at once. You can filter by locale to review one language at a time.