Difference between revisions of "GPG guide/Translation Guide"

From LibrePlanet
Jump to: navigation, search
 
(16 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
=Getting started=
 
=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.
+
So you want to translate the [https://emailselfdefense.fsf.org/ 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 [http://lists.fsf.org/mailman/listinfo/esd-translators esd-translators] list and and send a message stating your intention to translate and asking if there is anyone else that 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.
+
First, join the [http://lists.fsf.org/mailman/listinfo/esd-translators 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 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 access to the development site's repo.  
+
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======
+
===Using the git repository===
The in-development translations are stored in a git repository that is also served publicly to the web at enc-dev0.fsf.org/master. Once the FSF's tech team replies to you saying they have added your SSH public key, make a local checkout of it using [https://libreplanet.org/wiki/GPG_guide/Checking_Out 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.
+
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 [https://libreplanet.org/wiki/GPG_guide/Checking_Out 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.
 
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.
Line 16: Line 17:
 
Once you've pushed your changes, they should appear at enc-dev0.fsf.org/[YOUR LANGUAGE CODE]. Example: enc-dev0.fsf.org/de
 
Once you've pushed your changes, they should appear at enc-dev0.fsf.org/[YOUR LANGUAGE CODE]. Example: enc-dev0.fsf.org/de
  
======Setting up your local development environment======
+
===Setting up your local development environment===
 
You can view your local copies of the guide's HTML files, but they will not be styled at all. To see the guide the way it actually looks online while you are editing (recommended), you'll need to [https://libreplanet.org/wiki/GPG_guide/Setting_Up_Your_Local_Development_Environment set up an Apache server on your computer for development].
 
You can view your local copies of the guide's HTML files, but they will not be styled at all. To see the guide the way it actually looks online while you are editing (recommended), you'll need to [https://libreplanet.org/wiki/GPG_guide/Setting_Up_Your_Local_Development_Environment set up an Apache server on your computer for development].
  
Line 27: Line 28:
  
 
=Translating into Templates=
 
=Translating into Templates=
 +
===Starting New Translation===
 +
 +
The preferred way of translating is to start with a [https://www.gnu.org/software/gettext/ 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 [https://en.wikipedia.org/wiki/Poedit poedit], [https://www.emacswiki.org/emacs/PoMode 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.
  
===Starting New Translation===
+
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 <code>Makefile</code> located in the repository, and more details can be found in the [http://dev.man-online.org/man7/po4a/ po4a documentation].
  
The preferred way of translation is using a [https://www.gnu.org/software/gettext/ gettext] localisation template files PO. It is more convenient, 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 file as the translated version is generated automatically.
+
===Generating the Translated Version===
  
Empty template file for the web pages is esd-temp.pot located in the master branch of the git repository. Empty template file for the images is esd-svg-temp.pot located in the static repository.
+
After your translation is complete in the PO file, you need to generate the final HTML. The procedure is described in <code>Makefile.gen</code>, located at the root of the repository. To use it, you will need to install Make and po4a on your computer.
  
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 you translate the strings in your prefered PO editor. You can edit it using [https://en.wikipedia.org/wiki/Poedit poedit], [https://www.emacswiki.org/emacs/PoMode po-mode] in Emacs, or any other plain text editor.
+
The procedure for SVG is similar.
  
===Migrating Old Translation to PO files===
+
===Updating the Translation===
  
The po4a allows to extract the strings from the existing translation automatically. This saves the work which would be required by copying the and pasting the translated strings from the localised version into the PO templates.
+
When the English original is modified, the changes need to be merged into the POT and PO files. This is done by running:
  
However, this procedure might not be completely straightforward. This can be caused by conflicting translations of identical strings, or due to errors introduced into html files by manual editing.
+
<code>$ make esd-temp.pot</code>
  
The procedure on extracting the existing string is explained by Makefile located in the repository and more details can be found in the [http://dev.man-online.org/man7/po4a/ po4a documentation].
+
and
  
===Generating Translated Version===
+
<code>$ make esd-$lang.po.update</code>
  
After you finish your translation in the PO files, the final
+
Then you should update the translated strings and regenerate the HTML.
html and images are generated. The procedure is described in Makefile.gen script located in the in the repository. The script is commented with instructions instruction on how to generate the files. To use it you will need po4a installed on your computer.
 
  
 
===POEDIT===
 
===POEDIT===
Line 55: Line 70:
  
 
Then you will see the list of strings to be translated and two boxes in
 
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
+
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
 
be translated. The second box is where you write the translation in your
 
language.
 
language.
  
 
So, just go through all the strings and translate them one by one
 
So, just go through all the strings and translate them one by one
(remember saving the document once in a while).  If you need to see the
+
(remember to save the document once in a while).  If you need to see the
context of the string refer to the [https://emailselfdefense.fsf.org/en/ email self defense websites].
+
context of the string, refer to the [https://emailselfdefense.fsf.org/en/ email self defense websites].
  
 
=Elements to Translate=
 
=Elements to Translate=
Line 68: Line 83:
 
===Text on all pages===
 
===Text on all pages===
 
* index.html
 
* index.html
* mac.html
 
* windows.html
 
 
* next_steps.html
 
* next_steps.html
 
* confirmation.html
 
* confirmation.html
 
* infographic.html
 
* infographic.html
 
* workshops.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====
 
====Text Instructions====
There are three operating system pages: index.html (which is for GNU/Linux), windows.html and mac.html. They are exactly the same except for Section 1 and the troubleshooting section for Step 2.a. This should allow you to copy and paste for most of them.
+
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.
 
You don't need to translate anything that is commented out.
Line 93: Line 108:
  
 
====Graphics Instructions====
 
====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
 
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
 
directory. Translate them, using the closest you can find to the fonts
Line 98: Line 116:
 
sources. You may find the [[GPG_guide/Graphics_Howto | Graphics Howto]] useful if you have little experience with Inkscape.
 
sources. You may find the [[GPG_guide/Graphics_Howto | Graphics Howto]] useful if you have little experience with Inkscape.
  
Next you'll add your images to the static directory. This directory is a
+
Next you'll add your images to the static directory. Navigate to /static/img
submodule, so you'll need to run 'git submodule update' from the root
 
directory of the repo before working it. Then navigate to /static/img
 
 
and create a directory named after your language, like en. Put all your
 
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. For committing your changes in static submodule, see the
+
translated pngs into that directory. Even if an image does not have text, copy it into your language's directory in static.
simple instructions at https://libreplanet.org/wiki/GPG_guide/Checking_Out
 
  
 
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.
 
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===
 
===Source package===

Latest revision as of 12:24, 15 December 2022

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.

If you're a new git user, remember to run a git pull on your language directory before each session of translation work, and commit and push your changes when you sign off.

Once you've pushed your changes, they should appear at enc-dev0.fsf.org/[YOUR LANGUAGE CODE]. Example: enc-dev0.fsf.org/de

Setting up your local development environment

You can view your local copies of the guide's HTML files, but they will not be styled at all. To see the guide the way it actually looks online while you are editing (recommended), you'll need to set up an Apache server on your computer for development.

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

On all pages with a language picker, modify the language picker so that your language is the active class instead of English.


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:


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.