While it is possible to translate Tails custom programs using Transifex, this website, which includes the Tails documentation, can only be translated using our translation platform or Git.

This page explains how to get it up and running.

  1. Set up your tools
  2. How and what to translate?
  3. Workflow
  4. More informations and resources

Set up your tools

We recommend to use Tails to do your translations as it contains all the tools you need to set up a working environment.

If you want to use another operating system, these tools are:

  • Git - manage source code
  • Poedit - translate files
  • OpenSSH client - publish your translations on the server
  • tools to build a local copy of the website in order to check how it will look like

If you do not use Tails, please ensure that you use at least version 1.5 of Poedit, as this version handles line breaks correctly.

The following instructions assume that you are using Tails.

How and what to translate?

Once you have downloaded the Tails source code using Git, you can find the website source files in wiki/src.

The original website files are written in English, either in HTML or in Markdown. They have either a .html or a .mdwn extension.

These original files are not to be modified by translators. Instead, look for a file with the same name, but with the extension .po. Before this extension you will find the language code, for example fr for French.

To edit these PO files, we recommend that you use Poedit, a cross-platform editor for PO files.

When setting up Poedit, you might want to ensure to use "Tails translators" or "Tails developers" as translator name and "tails@boum.org" as translator contact email address.

If you do not use Poedit, but for example Vim or Emacs with the po-plugin, please verify for each translation that the syntax of the files is not broken. In order to do do so, please refer to the localization tricks page.

If there is no existing PO file for your language, you can copy the corresponding .pot file into a new .po file.

Workflow

Git makes it possible to work together on the same files and to track each modification. If you don't know Git yet, you might want to learn it first.

Here is the typical workflow used by Tails translation teams.

If there is any point which you don't understand, please do not hesitate to ask on the mailing list for translators, we will be glad to help you.

  1. Set up your own repository

    Fork us on our GitLab.

  2. Copy the source code from the main repository

    You first need to setup a Persistent Storage to save the source code. Then navigate to the Persistent folder, using the terminal:

    cd ~/Persistent

    Get the source code:

    git clone https://gitlab.tails.boum.org/tails/tails.git

    This operation requires some time at setup, as it requires pulling the whole repository.

    We use Git submodules, so after cloning this repository, in your new Git clone's directory, run:

    git submodule update --init

    For more information about our usage of Git submodules, see the dedicated section.

  3. Add your repository

    Navigate to the folder containg the source code, using the terminal:

    cd tails

    To publish your translations, you need to add the repository set up previously. The URL of your repository should look like git@gitlab-ssh.tails.boum.org:elouann/tails. If you cannot find the URL of your repository, get in touch with the sysadmins or send an email to the mailing list. Once you've got it, add it to your local repository:

    git remote add myrepo git@gitlab-ssh.tails.boum.org:elouann/tails

    Typing git remote should now show two entries:

    origin
myrepo

    More specifically, if you type git remote -v, you'll see something like this:

    myrepo   git@gitlab-ssh.tails.boum.org:elouann/tails (fetch)
myrepo   git@gitlab-ssh.tails.boum.org:elouann/tails (push)
origin   https://gitlab.tails.boum.org/tails/tails.git (fetch)
origin   https://gitlab.tails.boum.org/tails/tails.git (push)

    To check if the repository is correctly configured, run the following command:

    git fetch --all

    If you have a problem with SSH keys or with the URL of your repository, get in touch with the sysadmins or send an email to the mailing list.

  4. Configure your credentials

    Now to setup Git, type:

    git config user.name "Your nickname"
git config user.email "Your email adress"
git config apply.whitespace error

    Verify this configuration by typing:

    git config --list

  5. Install the pre-commit hook

    There is a script in ./bin/pre-commit-translation that can be used as a pre-commit hook. Please set it up as documented in the comments on top of that file. It will run some sanity checks on the translated files.

  6. Create a branch

    Create a branch for every translation you make, for example, if you want to translate the "contribute" page, create a branch named translate/contribute:

    git branch translate/contribute
git checkout translate/contribute

    Now typing git branch should show a star in front of the active branch:

      master
* translate/contribute

  7. Translate!

    You can use your preferred PO file editor, for example, Poedit which is included in Tails.

  8. Save your translations

    Add your changes, then commit

    git add -p
git commit

  9. Test your work

    Build the website locally in order to verify your modifications or to review the translations of somebody else.

    If you need to rework something, go back to step 5, translate, and test again.

  10. Merge our main repository into yours.

    Regularly, pull from the master branch of the main repository to update your local files.

    git fetch origin master only fetches new files, while

    git pull origin master fetches and merges the files.

  11. Publish your modifications

Push your changes to your online Git repository:

   git push myrepo <name of branch>

For example,

   git push myrepo translate/contribute

  1. Ask other members of your translation team to review your work by writing an email to the mailing list for translators, containing in its subject "(Review)" and the short code for the translated language, for example "[fr]".

  2. The reviewer, once happy with the result, should ask on the mailing list for translators to pull from the branch that was worked on, writing an email with "(pull)" and the language short code in the subject. Ideally, such email would be signed with OpenPGP.

Each language team keeps track of the repositories of its contributors. To add one of these repositories as a remote in Git, use the following command line:

git remote add [name] https://gitlab.tails.boum.org/[name]/tails.git

For example:

git remote add mercedes508 https://gitlab.tails.boum.org/mercedes508/tails.git

More informations and resources

The translation system used to translate Tails is called gettext. Every sentence that needs to be translated is written in a PO file by ikiwiki.

The [[!wikipedia ..]] strings you can find in some files are ikiwiki shortcuts. You might also need to understand ikiwiki directives.

See also localization tricks page.