## Translating applets

### Prepare translation function

Make sure the following two lines are imported in your `applet.js` file:

    1
    2

    const GLib = imports.gi.GLib;
    const Gettext = imports.gettext;

Add the following lines to your applet before `function MyApplet(...)`:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

    // l10n/translation support
    const UUID = "yourApplet@You";
    Gettext.bindtextdomain(UUID, GLib.get_home_dir() + "/.local/share/locale");

    function _(str) {
        return Gettext.dgettext(UUID, str);
    }

    function MyApplet(metadata, orientation, panelHeight, instance_id) {
    ......

And don't forget to change the `const UUID` above to your applets UUID.

### Prepare translatable strings

Every String in `applet.js` you want to be translated, needs to be put in brackets with underscore `_("")`, for example

    1

    _("This is a text, which needs to be translated")

### Create translation template for the first time

- Create a directory called `po` in the directory of your applet, where the `metadata.json` file is saved.
- Open a terminal in the directory where the `metadata.json` file is saved.
- Type in the command `cinnamon-json-makepot --js po/yourApplet.pot`

The command creates a translation template file `yourApplet.pot` in the `po` directory.

### Create a translation for the first time with the application Poedit

Install the programm "Poedit": `sudo apt install poedit`

- Open Poedit and click on `Create new translation`.
- Open the file `yourApplet.pot`.
- Once the file is loaded, Poedit will ask you to choose a language for the translation.
- At this point, the `.po` file can be saved and the name will automatically reflect the locale code.
- Poedit usage is pretty much straight forward:
  - There is the Source text box that contains the string to be translated (usually in English).
  - There is the Translation box that will contain the translated text.
  - If there is a `.mo` file saved, when you save your `.po` file, the `.mo` file should be deleted. You could also disable MO files creation from Poedit preferences (go to Edit > Preferences > General tab and uncheck the option called `Automatically compile MO file when saving`).

### Update an existing translation template

- Open a terminal in the directory where the `metadata.json` file is saved.
- Type in the command `cinnamon-json-makepot --js po/yourApplet.pot`

The command overwrites yours translation template file `yourApplet.pot` in the `po` directory.

### Updating an existing translation file

- Open the `.po` file with Poedit.
- Go to the menu `Catalog` and choose the `Update from POT file...` menu item.
- Select `yourApplet.pot` file from which your `.po` file was based on.
- Translate the new untranslated strings and save the changes.

### Testing your translations

The translations will be installed automatically, when the applet is installed through `System Settings > Applets > Applet available (online)`.

If you have installed your applet manually and you want to test your translations:

- Open a terminal in the directory where the `metadata.json` file is saved.
- Type in the command `cinnamon-json-makepot -i` to install the existing translations (i.e. the `.po` files)
- Restart Cinnamon: `CTRL+ALT+ESC`

If you want to remove your translations manually:

- Open a terminal in the directory where the `metadata.json` file is saved.
- Type in the command `cinnamon-json-makepot -r` to remove the installed translations.
- Restart Cinnamon: `CTRL+ALT+ESC`