Translations
############

Translations multiply the impact that Elgg can have
by making it accessible to a larger percentage of the world.

The community will always be indebted to those of you who work hard
to provide high quality translations for Elgg's UI and docs.

Transifex
=========

All translation for the Elgg project is organized through Transifex.

https://www.transifex.com/organization/elgg

Plugin authors are encouraged to coordinate translations via Transifex as well
so the whole community can be unified and make it really easy for translators
to contribute to any plugin in the Elgg ecosystem.

Pulling translations
--------------------

The translations made in Transifex need to be periodically pulled into the
Elgg code repository. This can be done with the script ``.scripts/languages.php``
bundled within Elgg's source code.

Prerequisites for running the script are:
 - Access to command line
 - `Git`_
 - `Transifex CLI tool`_

.. _Git: https://git-scm.com/
.. _Transifex CLI tool: https://docs.transifex.com/client/introduction

The script will do the following steps:
 1. Create a new git branch named ``{branch}_i18n_{timestamp}``
 2. Pull translations for all languages that have 95% of the strings translated
 3. Remove possible invalid language codes
 4. Commit the changes to the branch

After this you must push the branch to Github and make a new Pull request.

For example if you want to pull the translations for the ``3.x`` branch,
run the following commands:

.. code-block:: sh

    php .scripts/languages.php 3.x
    git push -u your_fork 3.x_i18n_1515151617

Run the command without parameters to get more detailed information of the usage.

Transifex configuration
-----------------------

The configuration for Transifex can be found from Elgg's source code in the
file ``.tx/config``.

This file defines:
 - The Transifex project associated with Elgg's major version
 - The location of all the files that have translatable content

Read the `Transifex documentation`_ for further details.

.. _Transifex documentation: https://docs.transifex.com/

New major Elgg version
----------------------

Every major version of Elgg must have its own project in Transifex. This way
we can make sure that strings added and removed between versions do not conflict
with each other. For example a translation key removed in Elgg 3 should not get
removed from translations made for Elgg 2. Respectfully a new string added only
to Elgg 3 should not be included in the translations meant for Elgg 2.

The process of setting up a new major version is:

 1. Pull latest translations from Transifex to the previous major version
 2. Merge the git branch of the previous version to the new to make sure all the
    latest translation keys are present
 3. Create a new Transifex project to https://app.transifex.com/elgg/
 4. Update ``.tx/config`` file in the development branch of the new major version

    - Update the configuration to point to the new Transifex project
    - Remove configuration of removed plugins
    - Add configuration for new plugins

 5. Push the translation sources to the new Transifex project with the command:
    ::

      tx push -s

 6. Copy the new configuration file temporarily (do not commit) to the previous
    major version, and push the existing translations from it to the new project:
    ::

      tx push -t -f --no-interactive

Later, once the dedicated branch (e.g. ``3.x`` has been created for the major version,
configure Transifex to fetch new translation keys from it automatically in
https://app.transifex.com/elgg/elgg-core-3/content/. This way you don't have to
repeat step 5 manually every time new translation keys are added.

It is important to always have a ``n.x`` branch besides the branches meant for
specific minor versions (``n.1``, ``n.2``, etc.). This way the URLs of the auto-update
sources do not have to be updated every time a new minor branch is created.
