bubble-ai-translator

AI-Powered Localization CLI & TUI for Bubble.io
Translate your entire Bubble.io app into 108+ languages using Google Gemini, OpenRouter, OpenAI, Anthropic, or Ollama (free, local).

What Is This?

Bubble.io's built-in localization is tedious: you export a CSV, manually translate thousands of rows, then re-import. This tool automates the entire pipeline — extraction, AI translation, and output — in a single command.

language_translation_data.csv  ──→  bubble-ai-translator  ──→  translated.csv
myapp.bubble                   ──→  bubble-ai-translator  ──→  myapp.translated.bubble

Key Features

• 📄 Official CSV format — reads and writes Bubble's language_translation_data.csv exactly
• 🫧 .bubble file parser — extracts App Texts, Option Sets, and inline page strings
• Any AI Provider: 5 built-in providers with smart context grouping:
  • 🖥️ Ollama (100% free & local, perfect for privacy)
  • ✨ Google AI Studio / Gemini (Fast and affordable)
  • 🌍 OpenRouter (Use any model in the world)
  • 🤖 OpenAI (GPT-4o, GPT-4o-mini)
  • 🧠 Anthropic (Claude Haiku, Sonnet, Opus)
• 💾 Translation Memory — SQLite cache, never pays twice for the same string
• 📚 Glossary — brand names and technical terms are never mistranslated
• 🧪 Pseudo-localization — [Ĥéllö Wörld~~~] for UI layout testing
• 👁️ Watch mode — re-translates incrementally when the file changes
• 🌐 Bubble Data API — sync translations directly to your database records
• 📊 Markdown reports — cost, cache hit rate, coverage per language
• 🖥️ Interactive TUI — guided wizard when run with no arguments

Requirements

| Requirement | Version | |-------------|---------| | Node.js | ≥ 22.0.0 (uses built-in node:sqlite) | | npm | ≥ 8 | | Ollama (optional) | any — for free local translation | | Google AI Studio key (optional)| for Gemini 2.5 Flash / 1.5 Pro | | OpenRouter API key (optional) | for any global LLM | | OpenAI API key (optional) | for GPT-4o-mini / GPT-4o | | Anthropic API key (optional) | for Claude Haiku / Sonnet |

Installation

# Clone the repository
git clone https://github.com/alexandrmotologa/bubble-io-ai-translator.git
cd bubble-io-ai-translator

# Install dependencies (no native compilation required)
npm install

# Build
npm run build

# Test the installation
npm start -- --version

Global install (optional):

npm install -g bubble-io-ai-translator
bubble-ai-translator --version
# or the short alias:
bat --version

Quick Start

Option 1: Interactive TUI (Recommended for first-time users)

npm start

Launches a step-by-step wizard:

● bubble-ai-translator  AI-Powered Localization for Bubble.io

? What would you like to do?
  ● Translate CSV (language_translation_data.csv)
  ○ Translate .bubble App File
  ○ Generate Pseudo-localization
  ○ Configure API keys & settings
  ○ View translation cache statistics

Option 2: CLI (Recommended for automation)

# Translate to Romanian and French using Ollama (free)
npm start -- translate \
  --file language_translation_data.csv \
  --langs ro_ro,fr_fr \
  --provider ollama

# Output: language_translation_data.translated.csv

All Commands

| Command | Description | |---------|-------------| | translate | Full pipeline: extract → AI translate → write output | | translate --dry-run | Preview what would be translated, no API calls made | | estimate | Show token count and cost estimate across all providers | | extract all | Export all strings to JSON | | extract languages | List all language codes in a file | | extract app-texts | Export App Text strings only | | extract option-sets | Export Option Set strings only | | config set | Save API keys and provider settings | | config show | Display current configuration | | config reset | Reset all settings to defaults | | pseudo | Generate pseudo-localized test file | | watch | Re-translate on file changes | | cache stats | Show translation memory statistics | | cache clear | Clear the translation cache | | glossary add | Add a term that must never be translated | | glossary list | List all protected terms | | glossary remove | Remove a glossary term |

Documentation

Full documentation is in the docs/ folder:

| Document | Description | |----------|-------------| | Getting Started | Installation, first translation, and configuration | | CLI Reference | Every command, option, and flag | | Providers Guide | Google, OpenRouter, OpenAI, Anthropic, and Ollama setup | | File Formats | CSV and .bubble file structure | | Translation Memory | Cache and glossary system | | Bubble Data API | Direct database sync via REST | | Architecture | Source code structure and design | | Contributing | How to contribute |

License

MIT © 2025 — see LICENSE