Localizing plugins to your language

All the plugins are created in English by default. If you want them to be available in your language, you can add translations to them.

Translating config.json sections

First you can translate the config.json file. To do that, open it and find all the strings in English. Usually they are name, variations.description and variations.buttons.text nodes of the configuration object.

Add the new nodes with the key name plus Locale, equal to an object that will have the language locale as the key and the translation as the value. For example, for the name key the localization object will look like this:

"name": "Highlight code",
"nameLocale": {
    "de": "Code hervorheben",
    "es": "Resaltar el código",
    "fr": "Code en surbrillance",
    "ru": "Подсветка кода"
}

The complete translations in the config.json for the code highlighting plugin will look the following way:

{
    "name": "Highlight code",
    "nameLocale": {
        "de": "Code hervorheben",
        "es": "Resaltar el código",
        "fr": "Code en surbrillance",
        "ru": "Подсветка кода"
    },
    ...,
    "variations": [
        {
            "description": "Highlight code",
            "descriptionLocale": {
                "de": "Code hervorheben",
                "es": "Resaltar el código",
                "fr": "Code en surbrillance",
                "ru": "Подсветка кода"
            },
            ...,
            "buttons": [
                {
                    "text": "Cancel",
                    "textLocale": {
                        "de": "Abbrechen",
                        "es": "Cancelar",
                        "fr": "Annuler",
                        "ru": "Отмена"
                    },
                    ...
                }
            ],
            ...
        }
    ]
}

Localizing index.html and plugin code files

Find all the strings you want to be localized from the index.html and the pluginCode.js files and create their list. Then create the translations folder in the plugin directory, so that the structure looked like this:

..
[translations]
config.json
index.html
pluginCode.js

Create the language .json files for each language you want to add the translations for with the language four-letter code for its name (e.g. de-DE.json). These files will contain the objects with the source (English) language words and phrases as keys and translations into the selected language as values. This is an example of the German translation:

{
    "Language": "Sprache",
    "Highlight": "Hervorheben",
    "Style": "Stil",
}

Once all the localization files are added, the plugin file structure will look like this:

..
[translations]
    de-DE.json
    es-ES.json
    fr-FR.json
    ru-RU.json
config.json
index.html
pluginCode.js

You can now replace the strings in the files with their translated values.

Applying translations to plugin

To apply the translations you will need to add unique IDs to each element which has the string value you want to localize. For instance, you want to localize the New button in this part of code:

<button>New</button>

Add the id attribute to it, so that it looked like this:

<button id="button_new">New</button>

After that add the window.Asc.plugin.onTranslate function to the pluginCode.js file:

window.Asc.plugin.onTranslate = function()
    {
        var label = document.getElementById("button_new");
        if (label)
            label.innerHTML = window.Asc.plugin.tr("New");
    }

The window.Asc.plugin.onTranslate function will be called right after the plugin startup and later in case the plugin language is changed.

If you need to localize more than one word/phrase, the window.Asc.plugin.onTranslate function can have the following appearance:

window.Asc.plugin.onTranslate = function()
    {
        document.getElementById("button_delete").innerHTML = window.Asc.plugin.tr("Delete");
        document.getElementById("button_new").innerHTML    = window.Asc.plugin.tr("New");
        document.getElementById("button_rename").innerHTML = window.Asc.plugin.tr("Rename");
        document.getElementById("button_run").innerHTML    = window.Asc.plugin.tr("Run");
    }

Where every line will represent the localized element, reached using the appropriate ID.

Please note, that the translation uses the .innerHTML method and thus can contain not only words and phrases, but also some HTML elements (tags, links, etc.) Do not forget to escape any quotes in the translations (like in any .json file) so that they worked correctly.

Now, once the editors are started, the current interface language will be used to determine if the plugin has the same locale translation. If it is so, the plugin language will be changed to fit the editor interface language and the translation will be applied.