Please read this page from the main YASEP interface
Translations

by whygee, version : 2012-09-14

How to translate pages for this site

 

General procedure

First, find a part you would like to translate. Little chunks (one or two pages) are OK, it's better to do tiny parts progressively to have more feedback. Ensure that no other translation is being undertaken for this part (ask me/whygee about what's going on by email or on the facebook page).

Do not hesitate to ask questions. The meaning of a term, whatever. Don't be shy!

On some places I have used Google Translate to get certain terms because I don't speak spanish well, so don't hesitate to modify the translations if you think a better term is more suitable. But be sure that it is used in the right context.

If a translation is missing, it's not critical as long as there is an english version, which serves as reference. There is no need to translate every little detail before the site works, thanks to the fallback mechanism. You can take your time to do things well.

Use a plain text editor to modify a file. The encoding is UTF8 and it should display "é" as "é". MS-Word or OpenOffice don't work nicely and destroy many hidded parts of the files. MS-wordpad or notepad can edit HTML and JavaScript files without too much disruption but UTF8 support is spotty.

Once translated, send me the file(s). I will review, edit, correct and integrate all the submission so don't worry too much about breaking anything. After the main site is updated, review the changes and ask your friends to get a better scrutiny :-)

All the files and data contributed to the site will be placed under the same Affero GPL license and (unless requested) the submitter's name will be added to the thanks page.

 

System messages

Most internal messages and language-dependent strings are stored in the file i8n.js. As of 20120915 that's 190 entries or idioms to translate and it increases slowly. I have left out some of the messages that are too unlikely to appear. The format of one message is :

nameOfTheMessage:[
    "message in english",
    "message en français",
    "mensaje en español"],

So if you translate to Spanish, add a coma and quotes at the end of the french translation, and include your own text. If there was no french text (or even nothing) at the 2nd position, just add a coma and your text : empty language messages can be written as null or just with nothing (but there must be a coma).

nameOfTheMessage:[
    "message in english",
    ,   // the french message is missing or identical to the english message
    "mensaje en español"],

 

HTML pages

There are many HTML pages that can be translated and they have a name ending in .en.html. There is a 2-letter language code before the HTML suffix, it indicates which language is used. The English versions are the reference and you should start with the .en.html and eventually use other languages (if you peak them) in case you have a doubt about the meaning.

Use a full-source editor, not a WYSIWYG editor and be sure that it understands UTF8. There are several hidden parts to take into account, particularly at the top of the page with the "hidden DIV" :

<div class="hiddenDiv">
  <span id="hidden0">Translations</span>
</div>

These blocks contain the title of the page and sometimes other snippets of text that will be dynamically inserted in the page.

And you will like to have syntax highlighting that shows the tags (that must not be modified).

 

The welcome page

The "Welcome" page is a bit special because it contains all the languages in one page, and also because it gets modified from index.dev.html to index.html to hold the compacted CSS and JavaScript codes. So after an update of the development page, the compacted page must be regenerated.

The contents is like all the other HTML pages however. There is the same "hiddendiv" system that must be translated. But the HTML contents is itself held in other DIVs that get hidden or shown on demand by the JavaScript code.

 

Adding a new language

Let's now imagine that you come from the country of H@ck and you want to adapt the whole site to your own language. First let's go to Wikipedia to determine the langage code : hc. This means that your translated pages will end with .hc.html.

Then grab the national flag in SVG : http://www.catb.org/hacker-emblem/glider.svg. Open it with suitable software (like the Gimp) to cleanly rasterize it to a size no more than 40px wide and 20px high (yes the UK flag is quite wide). Since this flag is square, the size is set to 20x20 and some graphics work is necessary to make it look decent when it's so small.

  

Normally you could reduce the color depth to just a few colors: use a low-count "palette" mode, not 24-bits RGB. Save the color file as both GIF and PNG file to the /logo directory and erase the largest of the two. For such small and simple pictures, GIF usually wins but you never know. The file's name must contain the language code to distinguish it from the others, in this case it's flag_hc.gif

-rw-rw-r--.  1 yg yg  224 sept. 14 01:20 flag_hc.gif  <= GIF wins again
-rw-rw-r--.  1 yg yg  267 sept. 14 01:21 flag_hc.png

Once the smallest file is saved, encode it to base64. I provide a small bash script called logos/mkcss.sh:

#!/bin/bash
# logos/mkcss.sh
#  arguments : $1=fichier, $2=largeur, $3=hauteur, $4=type, $5=language code
echo 'div.flag_'$5'{'
echo -n '  background: url(data:image/'$4';base64,'
base64 -w 0 $1
echo ') no-repeat center;'
echo '  width:'$2'px;'
echo '  height:'$3'px;'
echo '}'

So to encode it, type

$ ./mkcss.sh flag_hc.gif 20 20 gif hc

The result is some CSS code :

div.flag_hc{
  background: url(data:image/gif;base64,R0lGODdhFAAUAOMPAAAAAAgICA8PDzMzMz4+PlNTU1tbW2BgYHFxcYCAgIWFhcDAwMnJyenp6fDw8P///ywAAAAAFAAUAAAElVChOQul9qr0eufOcTgP55WmxwkAIJQnGidL2y7pl5eNDTS7RPChCAQUsFPCcEEMms6mYTh7NBa66kzREjiEWmXAdgArY6Vxq0xVcl3ftsqKLTEvz2aeMn0QAgIMHEVHJQwCAQQoCTYCCT02QCwtGwkFNgE0PjhqAAVCDDYEK10lBDaCHAwFSCAiJIMFDCUSFxm2TQoRADs=) no-repeat center;
  width:20px;
  height:20px;
}

Now copy the result and paste it at the end of logos/logos.css.

Finally, you have to update the internationalisation file : i8n.js. Add your language code and language name to the following arrays :

 // i8n.js :
i8n={
  LANGS:["en",
         "fr",
         "es",
         "hc"],
  LANGUAGES:["English",
             "Français",
             "Español",
             "H@ck"],

In this case, it means that H@ck is the 4th language in all the lists.

That's all. You have added a new supported language to the YASEP web site. The bulk of the work remains, at the time of writing there are about 80 english HTML files to translate...

Good luck and have fun !