# Translate Plugin
This plugin adds translation capabilities to the Jodit editor, allowing users to translate selected text directly within the editor. It provides a toolbar button for translation and supports different translation providers.
## Features
- Translate selected text with a single click
- Support for Google Translate API
- Support for custom translation providers
- Configurable source and target languages
- Keyboard shortcuts for quick translation
## Installation
```html
Translate Editor
```
## Options
### translate.provider
- Type: `'google' | ITranslateProviderFactory`
- Default: `'google'`
- Required: `true`
Translation engine provider. You can use:
- `'google'` - Google Translate API
- `'cloud'` - [Jodit Cloud](https://xdsoft.net/jodit/pro/docs/cloud/cloud.md) Translation service
- A custom function that implements the `ITranslateProviderFactory` interface (see [Custom Translate Provider](#custom-translate-provider) example)
```js
Jodit.make('#editor', {
translate: {
provider: 'google'
}
});
```
### translate.defaultSourceLang
- Type: `string`
- Default: `''` (empty string, which means auto-detection)
- Required: `false`
Default source language for translation. Use language [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes.
If not specified, the plugin will try to auto-detect the source language.
```js
Jodit.make('#editor', {
translate: {
defaultSourceLang: 'en'
}
});
```
### translate.defaultTargetLang
- Type: `string`
- Default: `'de'`
- Required: `true`
Default target language for translation. Use language [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes.
```js
Jodit.make('#editor', {
translate: {
defaultTargetLang: 'fr'
}
});
```
### translate.hotkeys
- Type: `object`
- Default:
```js
{
translateSelection: ['ctrl+shift+o', 'cmd+shift+o'],
translateOptions: ['ctrl+shift+p', 'cmd+shift+p']
}
```
Keyboard shortcuts for translation functions.
```js
Jodit.make('#editor', {
translate: {
hotkeys: {
translateSelection: ['ctrl+alt+t'],
translateOptions: ['ctrl+alt+o']
}
}
});
```
### translate.googleProviderOptions
- Type: `object`
- Default:
```js
{
url: 'https://translation.googleapis.com/language/translate/v2',
key: ''
}
```
Options for Google Translate API.
#### translate.googleProviderOptions.key
- Type: `string`
- Default: `''`
- Required: `true` (when using Google Translate provider)
API key for using Google Translate engine. [Get API key](https://cloud.google.com/console/)
```js
Jodit.make('#editor', {
translate: {
provider: 'google',
googleProviderOptions: {
key: 'YOUR_GOOGLE_API_KEY'
}
}
});
```
#### translate.googleProviderOptions.url
- Type: `string`
- Default: `'https://translation.googleapis.com/language/translate/v2'`
- Required: `false`
URL for Google Translate API. You typically don't need to change this unless you're using a proxy or a different endpoint.
```js
Jodit.make('#editor', {
translate: {
provider: 'google',
googleProviderOptions: {
url: 'https://your-proxy.com/google-translate',
key: 'YOUR_GOOGLE_API_KEY'
}
}
});
```
### translate.cloudProviderOptions
- Type: `object`
- Default:
```js
{
url: 'https://cloud.xdsoft.net',
key: ''
}
```
Options for [Jodit Cloud](https://xdsoft.net/jodit/pro/docs/cloud/cloud.md) Translation service.
#### translate.cloudProviderOptions.key
- Type: `string`
- Default: `''`
- Required: `true` (when using Cloud provider)
API key for [Jodit Cloud](https://xdsoft.net/jodit/pro/docs/cloud/cloud.md) Translation service.
```js
Jodit.make('#editor', {
translate: {
provider: 'cloud',
cloudProviderOptions: {
key: 'YOUR_CLOUD_API_KEY'
}
}
});
```
#### translate.cloudProviderOptions.url
- Type: `string`
- Default: `'https://cloud.xdsoft.net'`
- Required: `false`
Base URL for the Jodit Cloud Translation API. You typically don't need to change this unless you're using a self-hosted instance.
```js
Jodit.make('#editor', {
translate: {
provider: 'cloud',
cloudProviderOptions: {
url: 'https://your-instance.example.com',
key: 'YOUR_CLOUD_API_KEY'
}
}
});
```
## Custom Translate Provider
You can create your own translation provider by implementing the `ITranslateProviderFactory` interface. This function should return an object with two methods:
1. `translate(text, from, to)` - Translates text from one language to another
2. `supportedLanguages()` - Returns a list of supported languages
```js
import { JoditPro } from 'jodit-pro';
JoditPro.make('#editor', {
language: 'en',
buttons: ['translate.translate'],
extraPlugins: ['translate'],
translate: {
provider: (jodit) => {
return {
supportedLanguages() {
return Promise.resolve({
langs: {
English: 'en',
Russian: 'ru',
German: 'de'
}
});
},
translate(text, from, to) {
return fetch(
'https://your-translate-service.com/?text=' +
encodeURIComponent(text) +
'&from=' +
encodeURIComponent(from || jodit.o.language) +
'&to=' +
encodeURIComponent(to)
)
.then((resp) => resp.json())
.then((data) => {
return {
text: data.translation.text
};
});
}
};
}
}
});
```
## Usage Examples
### Basic Usage with Jodit Cloud
```js
import { JoditPro } from 'jodit-pro';
JoditPro.make('#editor', {
language: 'en',
buttons: ['translate.translate'],
extraPlugins: ['translate'],
translate: {
provider: 'cloud',
defaultSourceLang: '',
defaultTargetLang: 'en',
cloudProviderOptions: {
key: 'YOUR_CLOUD_API_KEY'
}
}
});
```
### Basic Usage with Google Translate
```js
import { JoditPro } from 'jodit-pro';
JoditPro.make('#editor', {
language: 'en',
buttons: ['translate.translate'],
extraPlugins: ['translate'],
translate: {
provider: 'google',
defaultSourceLang: 'en',
defaultTargetLang: 'fr',
googleProviderOptions: {
key: 'YOUR_GOOGLE_API_KEY'
}
}
});
```
### Using Custom Translation Service
```js
import { JoditPro } from 'jodit-pro';
JoditPro.make('#editor', {
language: 'en',
buttons: ['translate.translate'],
extraPlugins: ['translate'],
translate: {
provider: (jodit) => {
return {
supportedLanguages() {
// Return only the languages your service supports
return Promise.resolve({
langs: {
English: 'en',
Spanish: 'es',
French: 'fr',
German: 'de',
Italian: 'it'
}
});
},
translate(text, from, to) {
// Use your own translation API
return fetch(`https://api.your-translation-service.com/translate`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
text,
source_language: from || 'auto',
target_language: to
})
})
.then(response => response.json())
.then(data => {
return {
text: data.translated_text
};
});
}
};
},
defaultTargetLang: 'es'
}
});
```
### Customizing Keyboard Shortcuts
```js
import { JoditPro } from 'jodit-pro';
JoditPro.make('#editor', {
buttons: ['translate.translate'],
extraPlugins: ['translate'],
translate: {
provider: 'google',
googleProviderOptions: {
key: 'YOUR_GOOGLE_API_KEY'
},
hotkeys: {
translateSelection: ['alt+t'],
translateOptions: ['alt+o']
}
}
});
```
## API Reference
### Configuration Interface
```typescript
interface TranslateConfig {
provider: 'google' | 'cloud' | ITranslateProviderFactory; // Translation provider
defaultSourceLang: string; // Default source language (ISO-639-1)
defaultTargetLang: string; // Default target language (ISO-639-1)
hotkeys: {
translateSelection: string[]; // Shortcuts for translating selection
translateOptions: string[]; // Shortcuts for opening options
};
googleProviderOptions: IGoogleTranslateProviderOptions;
cloudProviderOptions: ICloudTranslateProviderOptions;
}
```
### Provider Interfaces
```typescript
interface ITranslateProviderFactory {
(jodit: IJodit): ITranslateProvider;
}
interface ITranslateProvider {
translate(text: string, from: string, to: string): Promise;
supportedLanguages(): Promise;
}
interface ITranslateResponse {
text: string; // Translated text
}
interface ITranslateSupportedLanguages {
langs: {
[title: string]: string; // Language name to ISO code mapping
};
}
```
### Cloud Provider Options
```typescript
interface ICloudTranslateProviderOptions {
url: string; // Jodit Cloud API base URL
key: string; // API key
}
interface ICloudTranslateResponse {
success: boolean;
text: string; // Translated text
}
```
### Google Provider Options
```typescript
interface IGoogleTranslateProviderOptions {
url: string; // Google Translate API endpoint
key: string; // Google API key
}
interface IGoogleTranslateResponse {
data: {
translations: Array<{
translatedText: string;
}>;
};
}
```
### State Interface
```typescript
interface ITranslateState {
sourceLang: string; // Current source language
targetLang: string; // Current target language
}
```
### Commands
The plugin adds the following editor commands:
```typescript
interface IJodit {
execCommand(command: 'translate'): void; // Translate selection (CMD+SHIFT+O)
execCommand(command: 'translateOptions'): void; // Open translate options (CMD+ALT+O)
}
```
## How It Works
1. When text is selected in the editor, the user can click the "Translate" button or use the keyboard shortcut
2. The plugin sends the selected text to the configured translation provider
3. The translated text replaces the selected text in the editor
4. Users can also access translation options to change source and target languages
This plugin is particularly useful for multilingual content creation and editing, allowing users to quickly translate portions of text without leaving the editor.