AI Translations

Loco integrates with the BlueHive AI API to batch-translate phrases automatically, preserving variable slots throughout.

Setup

1. Get a BlueHive API key (starts with BHSK-...) from bluehive.com
2. Add it in Dashboard → Settings → BlueHive API Key and click Save

Or set it as an environment variable (takes effect on next server start):

BLUEHIVE_API_KEY=BHSK-...

Running a translation job

1. Go to Dashboard → AI Translate
2. Select a target language and a prompt template
3. Choose phrases — all untranslated approved phrases, or a custom selection
4. Click Translate

The job runs in the background. You can watch progress in real-time and cancel at any time.

Job lifecycle

Created (pending) → Running → Completed
                           ↘ Failed
                           ↘ Cancelled

For each phrase in the job:

1. Strip {{type:N}} slot tokens from the key
2. Call BlueHive API with the prompt template
3. Restore slot tokens in the AI response
4. Upsert translation into the database
5. Update job progress counters

A 100 ms rate-limit delay is applied between API calls. Jobs are processed serially (one phrase at a time).

Prompt templates

Loco stores reusable prompt templates in the database. Go to Dashboard → Settings → Prompt Templates to create and edit them.

Template placeholders:

Placeholder	Replaced with
{{TEXT}}	The phrase text (slots already stripped)
{{CONTEXT}}	The DOM context string
{{TARGET_LANGUAGE}}	The target language name

Slot preservation

Variable slot tokens are handled automatically:

Input key:   "You have {{number:0}} pending tasks"
Sent to AI:  "You have  pending tasks"        ← slots stripped
AI returns:  "Vous avez  tâches en attente"
Stored as:   "Vous avez {{number:0}} tâches en attente"  ← slots restored

Job history

The last 50 jobs are retained in the ai_job_log table. Completed jobs are auto-cleaned after 10 minutes; failed jobs after 30 minutes. Full history is available in Dashboard → AI Translate → History.

API

Endpoint	Description
POST /api/ai-jobs	Create a job: { key_ids, lang, prompt_id, include_screenshots? }
GET /api/ai-jobs	List active jobs and stats
GET /api/ai-jobs/:jobId	Get job status and progress
DELETE /api/ai-jobs/:jobId	Cancel a running job
GET /api/ai-jobs/log	Recent job history (last 50)