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.
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.
Set up your own repository
Fork us on our GitLab.
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.
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.
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
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.
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
Translate!
You can use your preferred PO file editor, for example, Poedit which is included in Tails.
Save your translations
Add your changes, then commit
git add -p git commit
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.
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, whilegit pull origin master
fetches and merges the files.Publish your modifications
Push your changes to your online Git repository:
git push myrepo <name of branch>
For example,
git push myrepo translate/contribute
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]".
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.