Image to Image Text Translation Actor

Translate text within images while preserving the original layout, styling, and visual appearance. This Actor uses Google Cloud Vision API for text detection and Lingo.dev for high-quality translation with brand voice preservation.

Features

• 🔍 Smart Text Detection: Uses Google Cloud Vision API to detect text with precise bounding boxes
• 🌍 70+ Languages: Supports all major languages with regional variants
• 🎨 Visual Preservation: Maintains original colors, fonts, and layout
• 📏 Adaptive Sizing: Automatically adjusts font size and background for different text lengths
• 🔤 Alphanumeric Filtering: Only translates readable text (letters, numbers, spaces)
• 📁 Flexible Input: Supports both image URLs and file uploads
• 🤖 AI Image Editing: Uses Gemini's image editing to fix text overlaps directly

How It Works

1. Text Detection: Scans the image using Google Cloud Vision API
2. Smart Filtering: Only processes alphanumeric text (skips symbols, decorations)
3. Translation: Uses Lingo.dev for context-aware translation
4. Color Analysis: Detects original text colors and background patterns
5. Adaptive Rendering: Adjusts font size and background based on translation length
6. AI Quality Check: Vertex AI Gemini analyzes result for text overlaps and applies fixes
7. Image Composition: Overlays translated text while preserving visual integrity

Input

Field	Type	Required	Description
imageUrl	String	Yes	URL of the image to translate
targetLanguage	String	Yes	Target language (dropdown selection)
fontSize	Integer	No	Override font size (8-72px, default: auto-detect)
fontFamily	String	No	Font family (Arial, Helvetica, Times New Roman, Courier New)

Supported Languages

The Actor supports 70+ languages including:

• Major Languages: English, Spanish, French, German, Chinese, Japanese, Arabic, Russian
• Regional Variants: en-US, en-GB, es-ES, es-MX, zh-CN, zh-TW, etc.
• Specialized: Bavarian, Neapolitan, Tamazight, and more

Environment Variables

Set these as secret environment variables in the Apify Console:

Variable	Required	Description
LINGO_API_KEY	Yes	Your Lingo.dev API key
GOOGLE_APPLICATION_CREDENTIALS	Yes*	Path to Google Cloud service account JSON
GOOGLE_CLOUD_CREDENTIALS_JSON	Yes*	Google Cloud credentials as JSON string
GEMINI_API_KEY	No	Gemini API key for AI image editing (optional)

*Either Google Cloud credential method is required.

Setup Instructions

1. Get API Keys

Lingo.dev API Key:

1. Sign up at Lingo.dev
2. Create a new project
3. Generate an API key
4. Set as LINGO_API_KEY environment variable

Google Cloud Vision API:

1. Create a project in Google Cloud Console
2. Enable the Vision API
3. Create a service account with Vision API permissions
4. Download the JSON key file
5. Set as GOOGLE_CLOUD_CREDENTIALS_JSON environment variable

Gemini API (Optional):

1. Get API key from Google AI Studio
2. Set as GEMINI_API_KEY environment variable for AI image editing

2. Configure Environment Variables

In the Apify Console:

1. Go to your Actor settings
2. Add environment variables:
   • LINGO_API_KEY: Your Lingo.dev API key
   • GOOGLE_CLOUD_CREDENTIALS_JSON: Paste the entire JSON content
   • GEMINI_API_KEY: Your Gemini API key (optional, for AI image editing)

3. Run the Actor

1. Select target language from dropdown
2. Provide an image URL
3. Optionally adjust font settings
4. Run the Actor

Output

The Actor produces:

Dataset Items

{
  "originalUrl": "https://example.com/image.jpg",
  "originalType": "url",
  "originalFileName": null,
  "translatedImageUrl": "https://api.apify.com/v2/key-value-stores/.../translated-image.png",
  "targetLanguage": "es-ES",
  "processingTime": 3.2
}

Key-Value Store

• Translated Image: PNG file with translated text overlaid

Use Cases

• Marketing Localization: Translate ads, banners, and promotional materials
• E-commerce: Localize product images for international markets
• Documentation: Translate screenshots and diagrams
• Social Media: Adapt visual content for different regions
• Website Localization: Translate UI elements and graphics

Limitations

• Only processes alphanumeric text (letters, numbers, spaces)
• Requires clear, readable text in images
• Works best with horizontal text layouts
• Very complex backgrounds may affect color detection

Performance

• Processing Time: 8-12 seconds per image (including AI analysis)
• Supported Formats: JPEG, PNG, WebP, GIF
• Max Image Size: 10MB
• Concurrent Runs: Up to 100 (depending on plan)

Error Handling

Common errors and solutions:

Error	Cause	Solution
"No text detected"	Image has no readable text	Use images with clear text
"LINGO_API_KEY required"	Missing API key	Set environment variable
"Google Cloud credentials not found"	Missing credentials	Set Google Cloud environment variable
"No alphanumeric text found"	Only symbols/decorations detected	Use images with letters/numbers

Example Usage

Via Apify Console

1. Open the Actor in Apify Console
2. Provide an image URL
3. Select "Spanish (Spain)" as target language
4. Click "Start"

Via API

const { ApifyApi } = require('apify-client');

const client = new ApifyApi({
    token: 'your-apify-token'
});

const run = await client.actor('your-actor-id').call({
    imageUrl: 'https://example.com/image.jpg',
    targetLanguage: 'es-ES'
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log('Translated image:', items[0].translatedImageUrl);

Support

• Documentation: Apify Docs
• Community: Apify Discord
• Issues: Create an issue in this repository

License

This Actor is licensed under the Apache 2.0 License.