# How to translate

## Known bugs

`xgettext` will stop parsing a PHP file after a heredoc or nowdoc block.
Moving the translated strings above the first heredoc/nowdoc occurrence
will make the string available in the POT.

## Requirements

Environment: Linux Ubuntu (others may work).

```bash
# Add sudo if needed.
apt-get update && apt-get install gettext
```

## Generate POT file

The POT is the *PO template* file. It contains all the translatable strings of the plugin.

To update the .pot file, you can use the following command:

```bash
# Go to the plugin src folder.
cd /path/to/src

# Parse all PHP files and update the POT file.
find . -iname "*.php" | xargs xgettext --keyword=_dgettext:2c,3 --keyword=_dpgettext:2c,3 --from-code utf-8 --add-comments=i18n: -o _locale/_source/deployer-core.pot
```

This command also exports the comments above the gettext functions which start by `i18n:`.
This can be useful to add some context to the translators.

```php
// i18n: A comment to help the translator.
return _dpgettext( 'deployer-core', 'processor label', 'Map to import author' );
```

Also, please note that the `--keyword=_dpgettext:2c,3` option is used to parse the `_dpgettext` function.
This function is not available in the PHP implementation of gettext, so we have to use the `--keyword` option to tell `xgettext` (the e**X**tractor) to parse this function.

If other functions are used, you can add them to the `--keyword` option, like this:

```bash
# Simply repeat the --keyword option for each function,
# and specify the arguments position.
# See the xgettext documentation for more details.
--keyword=_dpgettext:2c,3 --keyword=_dgettext:2 --keyword=_n:1,2 --keyword=_dn:2,3 --keyword=_dpn:2c,3,4
```

To parse the original functions, simply remove the `--keyword` option.

> Note: the POT file is not needed for the plugin to work.
> It would be better to not bundle this file with the plugin.

## Create a new language, or update an existing one (PO file)

You can use Poedit (free third-party editor), or you preferred editor.

Based on a POT file, you can create a new PO file. The PO file is the file that contains the translations.

If the PO file already exists for a language, you can update it instead of starting from scratch.
But remember to update the POT file first to get the latest strings.

Save the PO file to `src/_locale/<language>/LC_MESSAGES/<domain>.po`.

- `<language>` is the language code, e.g.: `fr_FR`, `fr`.
- `<domain>` is the plugin domain, i.e.: `deployer-core` (it's the only domain for now).

> Note: the PO file is not needed for the plugin to work.
> It would be better to not bundle this file with the plugin.

## Export the MO file

The MO file is the machine object file. It's the file that contains the PO translations in a binary format.

Place this file in the `src/_locale/<language>/LC_MESSAGES` folder, beside the PO file.
