@builder.io/plugin-lokalise

Complete Lokalise translation integration for Builder.io - seamlessly translate your Builder.io content through Lokalise's professional translation platform.

📦 Installation

Option 1: Direct Plugin URL (Recommended)

Add plugin URL in Builder.io: https://unpkg.com/@hgillispie/lokalise-plugin@latest/dist/plugin.system.js

Option 2: Builder.io Plugin Directory

From the plugins tab in Builder.io, search for lokalise or use package name @hgillispie/lokalise-plugin

Option 3: NPM (for developers)

npm install @hgillispie/lokalise-plugin

Configuration

1. Get your Lokalise API token from Profile > API tokens in your Lokalise dashboard
2. Get your Project ID from your Lokalise project settings
3. Configure the plugin in Builder.io with these credentials

Translating content

What's being translated:

• All text elements in builder content [you can exclude specific element by right click + exclude from future translations]
• All custom fields in content that are marked as localized

From what language? The source language should match your Lokalise project base language.

To what languages? Select target languages from your Lokalise project's available languages in the translation job configuration.

How To translate?

• Prepare translation jobs by adding contents to draft jobs by pressing "Add to translation job" in content options or "Translate" in bulk actions
• Configure the job with your Lokalise project and target languages
• Press "Send to Lokalise" to upload content and create translation tasks
• Translate content in Lokalise dashboard or assign to translators
• Use "Apply Translation" to pull completed translations back to Builder

Features

• Automatic Content Extraction: Extracts translatable text from Builder content
• Project Integration: Works with existing Lokalise projects and languages
• Task Management: Optionally creates translation tasks in Lokalise
• Webhook Support: Handles real-time updates from Lokalise (when configured)
• Bulk Operations: Translate multiple content items at once
• Element-level Control: Exclude specific text elements from translation

Webhook Configuration (Optional)

To enable automatic translation updates:

1. In your Lokalise project, go to Settings > Webhooks
2. Add a new webhook pointing to your Builder webhook endpoint
3. Subscribe to events like project.translation.updated and project.task.completed

🐛 Troubleshooting

Configuration Issues

• Ensure your Lokalise API token has read/write permissions
• Verify the project ID exists and you have access
• Check backend API connectivity at https://talented-delight-production.up.railway.app/health

Plugin Reset (Development/Testing)

If you need to reset the plugin configuration for testing or debugging:

Method 1: Browser Console (Recommended)

resetLokalisePlugin()

Then refresh the page to see the configuration dialog.

Method 2: URL Parameter Add ?resetPlugin=true to your Builder.io URL, which will:

• Clear all plugin settings and localStorage
• Automatically reload the page
• Show the configuration dialog

Translation Job Issues

• Ensure content is published before adding to translation jobs
• Verify target languages are available in your Lokalise project
• Check console logs for detailed error information
• Make sure your Lokalise project has the correct base language set

Content Extraction Issues

• Only published content can be extracted for translation
• Complex nested components may require custom configuration
• Check that content contains translatable text strings
• Verify content has Text components with actual text content

Future Enhancements

• Automatic application of completed translations via webhooks
• Support for more file formats and translation workflows
• Integration with translation memory and glossaries
• Including custom components localized text inputs