Readme.md

Multilingual Plugin

Overview

Multilingual Plugin is an advanced plugin that allows easy addition and management of translations while editing objects. It supports multiple languages and enables users to define and manage their own language sets.

Configuration Steps

1. First, select the Content Types.
2. Add at least two languages and select the default language.
3. After saving the settings, the Content Types are modified and a __translations field is added, containing an array of available translations. The translation language is available under the __language field in each __translations item.

DeepL configuration

The plugin can use DeepL to generate translations automatically. To enable it, provide a DeepL API key in the plugin settings and add DeepL configuration for each content type that should support automatic translation.

For every DeepL configuration entry:

• Select the content type.
• Select the fields that should be sent to DeepL. Only text-based fields are available: text, textarea, richtext, and textMarkdown. The slug field is excluded.

DeepL configuration is optional. If the API key or configuration for a content type is missing, the object form will still use manual multilingual tabs, but the DeepL translation button will not be displayed.

Special Fields

• __translations: Contains an array of translations, excluding the default language, whose data is found in the object fields.
• __language: Specifies the translation language. Language is saved in ISO 639 language codes.

Warning! The __translations field should not be manually modified. After each change in the content type for translated fields, go to the plugin settings and save them again to properly update the translation fields.

Plugin Usage

• When adding/editing an object, tabs with the previously selected languages will be available. The default language is always in the first tab.
• Clicking on another language tab will add the translated fields, populated with the current fields in the default language.
• If we return to the default language tab, make changes, and go back to another language tab, the previously filled fields will not be overwritten.
• If DeepL is configured for the current content type, a Translate button is displayed next to the language tabs. Clicking it sends the configured field values from the default language to DeepL and fills translations for all configured languages except the default one.
• Existing translated values are updated for matching languages. If a translation for a language does not exist yet, the plugin creates it.
• After the DeepL request finishes, the plugin shows a notification with translated languages or errors, for example when DeepL does not support one of the selected languages.

Removing Content Type from plugin settings

When removing the content type from the settings, you will be asked whether to keep the translations or remove them:

• Removing: Modifies the content type, removes the __translations field, and deletes the collected data.
• Keeping: If you choose the "Keep translation fields" option, you can remove __translations field later manually by editing the content type.

Example object

Let's assume you have an object with title and slug fields. Before applying translations, your object will look like:

{
  "title": "My first blog post",
  "slug": "my-first-blog-post"
}

Now, let's consider that you are adding two languages: Polish and English, and your default language is English. After applying translations, the object will be:

{
  "title": "My first blog post",
  "slug": "my-first-blog-post",
  "__translations": [
    {
      "__language": "pl",
      "title": "Mój pierwszy post na blogu",
      "slug": "my-first-blog-post"
    }
  ]
}

Plugins events

flotiq-multilingual.translation::changed

Multilingual Plugin sends information to other plugins when a translation has been updated (or added). To use this information in your plugin, you need to listen to the event flotiq-multilingual.translation::changed.

Event properties:

Property	Description
fieldName	Translation field name with language index, eg. __translations.[0]
newTranslation	Full translation object
contentType	Content type that includes the field
initialData	Initial data of the content object. This will be either an empty object or the object being edited.
language	Language in ISO 639 language code

flotiq-multilingual.translation::update

Multilingual Plugin is listening to event from other plugins for updating translations. If you want Multilingual Plugin to create or update existing translation use flotiq-multilingual.translation::update event.

Event properties:

Property	Description
values	Translated fields, eg. {"name": "New value"}
language	Language in ISO 639 language code
contentType	Content type that includes the field
initialData	Initial data of the content object. This will be either an empty object or the object being edited.
formUniqueKey	Unique key from flotiq form events.

Development

Quick start

1. yarn - to install dependencies
2. yarn start - to start development mode - rebuild on file modifications
3. update your plugin-manifest.json file to contain the production URL and other plugin information
4. yarn build - to build plugins

Dev environment

Dev environment is configured to use:

• prettier - best used with automatic format on save in IDE, remember to run yarn format before commiting changes
• eslint - it is built into both start and build commands

Output

The plugins are built into a single dist/index.js file. The manifest is copied to dist/plugin-manifest.json file.

Deployment

Loading the plugin

Warning: While developing, you can use https://localhost:3053/plugin-manifest.json address to load the plugin manifest. Make sure your browser trusts the local certificate on the latter, to be able to use it e.g. with https://editor.flotiq.com

URL

Hint: You can use localhost url from development mode https://localhost:3053/index.js

1. Open Flotiq editor
2. Open Chrome Dev console
3. Execute the following script

   FlotiqPlugins.loadPlugin("plugin-id", "<URL TO COMPILED JS>");

4. Navigate to the view that is modified by the plugin

Directly

1. Open Flotiq editor
2. Open Chrome Dev console
3. Paste the content of dist/index.js
4. Navigate to the view that is modified by the plugin

Deployment

Hint: You can use localhost url from development mode https://localhost:3053/plugin-manifest.json

1. Open Flotiq editor
2. Add a new plugin and paste the URL to the hosted plugin-manifest.json file
3. Navigate to the view that is modified by the plugin

Collaborating

If you wish to talk with us about this project, feel free to hop on our .

If you found a bug, please report it in issues.