Koha/docs/development/internationalization.md

# Internationalization

This page documents how internationalization works in Koha.

## Making strings translatable

There are several ways of making a string translatable, depending on where it
is located

### In Template::Toolkit files (`*.tt`)

The simplest way to make a string translatable in a template is to do nothing.
Templates are parsed as HTML files and almost all text nodes are considered as
translatable strings. This also includes some attributes like `title` and
`placeholder`.

This method has some downsides: you don't have full control over what would
appear in PO files and you cannot use plural forms or context. In order to do
that you have to use `i18n.inc`

`i18n.inc` contains several macros that, when used, make a string translatable.
The first thing to do is to make these macros available by adding

    [% PROCESS 'i18n.inc' %]

at the top of the template file. Then you can use those macros.

The simplest one is `t(msgid)`

    [% t('This is a translatable string') %]

You can also use variable substitution with `tx(msgid, vars)`

    [% tx('Hello, {name}', { name = 'World' }) %]

You can use plural forms with `tn(msgid, msgid_plural, count)`

    [% tn('a child', 'several children', number_of_children) %]

You can add context, to help translators when a term is ambiguous, with
`tp(msgctxt, msgid)`

    [% tp('verb', 'order') %]
    [% tp('noun', 'order') %]

Or any combinations of the above

    [% tnpx('bibliographic record', '{count} item', '{count} items', items_count, { count = items_count }) %]

### In JavaScript files (`*.js`)

Like in templates, you have several functions available. Just replace `t` by `__`.

    __('This is a translatable string');
    __npx('bibliographic record, '{count} item', '{count} items', items_count, { count: items_count });

### In Perl files (`*.pl`, `*.pm`)

You will have to add

    use Koha::I18N;

at the top of the file, and then the same functions as above will be available.

    __('This is a translatable string');
    __npx('bibliographic record, '{count} item', '{count} items', $items_count, count => $items_count);

### In installer and preferences YAML files (`*.yml`)

Nothing special to do here. All strings will be automatically translatable.

## Manipulating PO files

Once strings have been made translatable in source files, they have to be
extracted into PO files and uploaded on https://translate.koha-community.org/
so they can be translated.

### Install gulp first

The next sections rely on gulp. If it's not installed, run the following
commands:

    # as root
    npm install gulp-cli -g

    # as normal user, from the root of Koha repository
    yarn

### Create PO files for a new language

If you want to add translations for a new language, you have to create the
missing PO files. You can do that by executing the following command:

    # Replace xx-XX by your language tag
    gulp po:create --lang xx-XX

New PO files will be available in `misc/translator/po`.

### Update PO files with new strings

When new features or bugfixes are added to Koha, new translatable strings can
be added, other can be removed or modified, and the PO file become out of sync.

To be able to translate the new or modified strings, you have to update PO
files. This can be done by executing the following command:

    # Update PO files for all languages
    gulp po:update

    # or only one language
    gulp po:update --lang xx-XX

### Only extract strings

Creating or updating PO files automatically extract strings, but if for some
reasons you want to only extract strings without touching PO files, you can run
the following command:

    gulp po:extract

POT files will be available in `misc/translator`.