npm package: @hgillispie/lokalise-plugin
Description: Lokalise translation integration for Builder.io - Complete translation workflow from Builder.io to Lokalise and back
Author: Hunter Gillispie
Latest version: 1.0.8

# @builder.io/plugin-lokalise

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

[![npm version](https://badge.fury.io/js/%40builder.io%2Fplugin-lokalise.svg)](https://badge.fury.io/js/%40builder.io%2Fplugin-lokalise)

## 📦 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)
```bash
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)**
```javascript
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