GPG guide/Translation Guide

Getting started

So you want to translate the FSF's guide to email encryption? Great! To translate, you'll have to know or be willing to learn basic-level HTML, git and SSH, and possess fluency in English as well as the target language. If you're not comfortable with the technical tools but would like to translate, we recommend you find a friend with these skills and work with them.

First, join the esd-translators list and and send a message stating your intention to translate and asking if there is anyone else who would like to collaborate with you. This avoids multiple separate efforts on the same translation. As you translate, feel free to use this list to ask questions or share ideas and suggestions for the guide.

Next, send an unencrypted email addressed to <sysadmin@fsf.org> CC <campaigns@fsf.org> with your SSH-RSA public key attached. Include the language(s) you are translating in the subject line and ask for access in the body. The FSF tech team will give you access to the development site's repo (enc) and you can push your changes to this repo.

Using the git repository

The in-development translations are stored in a git repository that is also served publicly to the web at https://enc-dev0.fsf.org/, updated once every 10 minutes. Once the FSF's tech team replies to you saying they have added your SSH-RSA public key, make a local checkout of it using these instructions. While you are editing it, use git branch to make sure you are on the master branch of the repository. If you are not on the master branch for some reason, use git checkout master.

Check if there is already a directory for your language (it may exist but not be visible on the live site because it is incomplete). If there is not a directory for it yet, copy the en directory to a new directory with your language's language code. Now you are ready to start translating. Feel free to commit unfinished work to the development site, or to wait until you are finished to commit. However, make sure you start committing from the beginning if you want to collaborate with others. It is important that you only edit your own language's directory. If you find a typo or other issue with the English version, please let the FSF know, rather than fixing it yourself.

Remember to run git pull in your language directory before each session of translation work, and commit and push your changes when you sign off.

You can view your local copies of the guide's HTML files in a web browser with the correct style. Once you've pushed your changes, they should appear at enc-dev0.fsf.org/[YOUR LANGUAGE CODE]. The only difference with the final version is the absence of a language picker. Example: enc-dev0.fsf.org/de

Working as an effective team

You are responsible for communicating with your fellow translators working in your language, but please let the FSF know if you experience any issues or need help resolving a conflict.

Review

Please have at least one person review everything that is translated, comparing the original and target texts. This person needs to be able to speak English as well as the target language. If a piece of text was translated by two or more people working as a team, that counts as well. In short, at least two sets of bilingual eyes should have seen everything before the translation is complete. It can be tempting to skip this step, but it is important to avoid miscommunicating carefully crafted security advice. If it's difficult to find someone qualified to review for you, ask the esd-translators email list. It's possible someone working on a different language may know yours as well.

Translating into Templates

Starting New Translation

The preferred way of translating is to start with a gettext localization template (POT file). This is more convenient than direct translation of the pages, because identical strings which are repeated on multiple pages are identified, and need to be translated only once. Also, you don't have to worry about editing HTML files, as the translated version is generated automatically.

The empty template file for the web pages is esd-temp.pot. It is located at the root of the master branch of the Git repository. The empty template file for images is esd-svg-temp.pot, located in the enc/static directory.

If you are starting a new translation, copy the empty template, e.g. esd-temp.pot, into esd-$lang.po where $lang is your language code. Then translate the strings in your preferred PO editor. You can edit it using poedit, po-mode in Emacs, or any other plain text editor.

Migrating Old Translations to PO files

[As of March 2019, all existing translations have POs in the Git repo, except ru and fr.]

Po4a is able to extract the strings from the existing translation automatically. This saves the work which would be required to copy and paste the translated strings from the localized version into the PO templates.

However, this procedure is not completely straightforward. Problems may arise from conflicting translations of identical strings, or from differences introduced into HTML files by manual editing.

The procedure for extracting the existing strings is explained in the Makefile located in the repository, and more details can be found in the po4a documentation.

Generating the Translated Version

After your translation is complete in the PO file, you need to generate the final HTML. The procedure is described in Makefile.gen, located at the root of the repository. To use it, you will need to install Make and po4a on your computer.

The procedure for SVG is similar.

Updating the Translation

When the English original is modified, the changes need to be merged into the POT and PO files. This is done by running:

$ make esd-temp.pot

and

$ make esd-$lang.po.update

Then you should update the translated strings and regenerate the HTML.

POEDIT

Poedit is a freely licensed GUI based PO editor. Once you downloaded and installed the poedit on your computer, run it and open the esd-$lang.po file by choosing open in poedit.

Then you will see the list of strings to be translated and two boxes in the Poedit window. In the first box you can see the original string to be translated. The second box is where you write the translation in your language.

So, just go through all the strings and translate them one by one (remember to save the document once in a while). If you need to see the context of the string, refer to the email self defense websites.

Elements to Translate

It is important that you only edit your own language's directory. If you find a typo or other issue with the English version, please let the FSF know, rather than fixing it yourself.

Text on all pages

• index.html
• next_steps.html
• confirmation.html
• infographic.html
• workshops.html
• mac.html (this page doesn't exist with the 2021 update)
• windows.html (this page doesn't exist with the 2021 update)

Text Instructions

There are three operating systems discussed: GNU/Linux, windows.html and mac.html. In Section 1 you will find a dropdown for macOS and Windows, the rest of the guide is the same for all three systems.

You don't need to translate anything that is commented out.

Make sure to translate the text in the sharing URLs, which are the ones with URLs that start with fsf.org/share. The URLs include the text of the message that will be shared, and that's what must be translated. Once you've translated them, click on them from the page and try sharing with a few different methods and check for formatting errors. You will need to not use hashtags in the sharing links because, ironically, they mess up our Twitter sharing.

Language Picker

The language picker is not in the POT file anymore. It is globally inserted into HTML pages when they are ready to go live.

Graphics

• join and donate buttons
• all inline images
• infographic and "view and share our infographic" thumbnail image
  • Edit the large URL at the bottom of the infographic to point to your translation, by adding your two letter language code to the end. For an example, see [1].

Graphics Instructions

For converting the old static submodule into a regular directory, see the simple instructions at GPG_guide/Checking_Out.

You can get the image source files from the source package in the /en directory. Translate them, using the closest you can find to the fonts in the source package for your language, then create the pngs from the sources. You may find the Graphics Howto useful if you have little experience with Inkscape.

Next you'll add your images to the static directory. Navigate to /static/img and create a directory named after your language, like en. Put all your translated pngs into that directory. Even if an image does not have text, copy it into your language's directory in static.

Once you're done with this, edit the HTML in your language's pages to call the images from your language's directory in static. Even if an image does not have text, call the copy in your language's directory.

Source package

You can use the .zip source package in /en as a model for this. Make sure to translate the README as well. Even if an image isn't translated because there is not text, it should still be in the source package for your language.

The source package also includes the text of the messages for Edward the reply bot, which you should translate as well. This is the only place on the site where Edward's text is. Please preserve the numbers above each message and the "Subject" and "Body" tags so that the FSF's English-speaking sysadmins know what to put where.

When you are done, compress it and commit it as a single archive.

Remember to update this when you change an image.

Note: don't forget to remove the (normally hidden) backup files before compressing, for 2 reasons:

• to keep the archive as light as possible,
• to remove any non-anonymized SVG if you have anonymized the new version.

Links

If a link points to something that you can easily find a translation of in your language hosted by the FSF or GNU, please modify the link to point to it. If you find a translation by someone else, please let the FSF know and we will review the translation to see if we can link to it instead.

Make sure to test all links and buttons.

Test any forms.

Preserve HTTP/HTTPS.

Attribution and licensing

If you'd like to get credit for your work, add your name to the commented-out attribution line in the footer and comment it back in. Make sure to do this on all pages.

Please don't change the licensing info on the page there - this means that your translation will be copyright FSF under the terms currently in the footer. If you are concerned about a licensing question, let us know. Make sure the footer is the same on all translated pages.

Submitting your translation

When your translation is completely finished and visible on the development site, send <campaigns@fsf.org> an email and request that it be published. Please confirm in your email that it has been reviewed by at least one other person who confidently speaks English, as well as the target language. The FSF will then push your guide to the live version of the site and add it to the language list in the header. We invite you to stay on the esd-translators email list after you are done to help new translators.