Installation of additional languages for OPAC and INTRANET staff client

== Introduction ==
The Koha OPAC and staff interface are translated into a lot of languages. There are a lot of complete translates, but there are also a lot of partial translations available. If you want to help translating, please take a look at the Translating Koha page.
All the text you see in Koha can be stored in 2 different places:
* Templates
* Database (item type descriptions, patron categories, authorised values, ...)
The translation process described here is about managing the template translations. po files are used to store the translations and the latest version of the files will be included in every release.
Important: The descriptions stored in the database can be changed from the staff interface. For some languages translators have provided translated data for the web installer. If you want to make use of those, make sure that you install your preferred language before running the web installer for the first time!
== Installing translations ==
Depending on the version of Koha and the way it was installed, the commands for installing languages are slightly different. The <language-code> usually is in the form of xx-YY. For example: de-DE = German, fr-FR = French, es-ES = Spanish.
Important: After installing a new language, you have to activate them under Administration > System preferences > Tab I18N/L10N. Look for language and opaclanguages.
=== Packages (current versions) ===
Starting with version 3.12, the Koha packages provide a convenient helper script that handles the install process of translations: koha-translate.
To get a list of the installed languages run:
 $ sudo koha-translate --list
To get a list of the available languages run:
 $ sudo koha-translate --list --available
To install a new language run:
 $ sudo koha-translate --install <language-code>
For further options run:
 $ sudo koha-translate --help
=== Packages (older versions) ===
In package installations older than 3.12, additional languages for the OPAC and staff interface can be added any time using the following instructions:
First you have to specify the location of your Koha Perl modules and of the koha-conf-site.xml.in file:
 $ export KOHA_CONF=/etc/koha/koha-conf-site.xml.in
 $ export PERL5LIB=/usr/share/koha/lib/
Then install the desired language with the command:
 $ cd /usr/share/koha/misc/translator
 $ sudo perl translate install <language-code>
Example:
 $ sudo perl translate install fr-FR
=== Tarball or git ===
Since Koha 3.2: If you have a tarball or git installation, you can add additional languages for the OPAC and staff interface at any time by following these instructions:
First you have to specify the location of koha perl modules and of the koha-conf.xml file, e.g.:
 $ export KOHA_CONF=<path_to>/koha-conf.xml
 $ export PERL5LIB=<koha_install_dir>/lib/
Then install the desired language with the command:
 $ cd <koha_install_dir>/misc/translator
 $ sudo perl translate install <language-code>
Example:
 $ sudo perl translate install fr-FR
Check the paths on your own installation. To find them, for e.g. you could run:
 $ sudo updatedb
(might take a while) and then:
 $ locate koha-conf.xml
=== kohadevbox (development environment) ===
If using a kohadevbox environment, both the package and the git instructions will work. The git instructions should be run within the koha-shell so that the environment variables are set correctly.
== Installing a translation on a development environment ==
In order to install a translation and have it detected by the I18N/L10N System Preferences the --dev flag must be used when installing a translation.
 $ sudo koha-translate --install fr-FR --dev <dev instance name>
The default dev instance name is kohadev.
== Removing an installed translation ==
If a non-existing language, e.g. de-XY, is installed, the perl translate script will error out.
The language directories, however, might have already been created:
 <koha_install_dir>/opac/htdocs/opac-tmpl/bootstrap
 <koha_install_dir>/opac/htdocs/opac-tmpl/prog
 <koha_install_dir>/opac/htdocs/opac-tmpl/ccsr
 <koha_install_dir>/intranet/htdocs/intranet-tmpl/prog
and the language is presented as a choice in the system preferences interface.
If you are using a package installation (3.12+), you can just run:
 $ koha-translate --remove <language-code>
On other setups, simply removing the aforementioned directories will also remove the language code from the system preference selection.
See also: notes on koha-testing-docker translation files
== Broken po files ==
Sometimes it can happen, that a release contains outdated or invalid translations files. Sometimes the translation process won't complete if there are errors in one or more of the po files. In this case it can be helpful to download the latest pos files from Koha's translation server. In order to find the errors if they are not fixed yet, tools like PoEdit can be helpful (more tools under Translating Koha).
You can replace the po files in your misc/translator/po directory with the downloaded files of the right version and reinstall the language.
== See also ==
* Correcting Search of Arabic records
* Translating Koha
Category:Translation
Category:Documentation
Category:Installation