Table of Contents ***************** GNU Web Translators Manual 1 Introduction 2 Team Members 2.1 Joining A Team 2.2 How To Submit a Translation 2.2.1 How To Submit a Translation in PO Format 2.2.2 How To Submit a Translation as Plain Text 2.3 Leaving A Team 3 Team Co-ordinators 3.1 How To Form A New Team 3.2 The Gentle Art of Managing A Translation Team 3.2.1 Peer Review 3.2.1.1 How To Track Tasks and Bugs Using Savannah 3.2.1.2 How To Proceed With Unreviewed Translations 3.2.2 CVS Commits And Best Practices 3.2.3 Taking Advantage of Savannah 3.2.3.1 Managing Members 3.2.3.2 Homepage of The Team 3.2.3.3 Support Tracker 3.2.3.4 Tasks Tracker 3.2.3.5 Bugs Tracker 3.2.3.6 Patch Tracker 3.2.3.7 News Tracker 3.2.3.8 Managing Mailing Lists 3.2.3.9 Version Control Systems 3.2.4 Promoting Members As Co-leaders 3.3 Reporting Team Status 3.4 How To Retire Painlessly 4 `trans-coord' Admins 5 Details About The Translation Process 5.1 Migration To The New Style 5.2 Summary of SSI `#include's 5.3 How To Use Custom CSS 5.3.1 Localizing The `topbanner' Image 5.3.2 Specific Issues Related to RTL 5.4 What To Translate 5.5 When To CAPITALIZE 5.6 Distribution Terms 5.7 Language-specific Terminology 6 Overview Of The Translation Process 6.1 Related Mailing Lists 6.2 Savannah Projects Membership Appendix A GNU Free Documentation License GNU Web Translators Manual ************************** This manual is a guide for the GNU Web Translators. Last updated on 08.02.2012, for GNUnited Nations version 0.5. Copyright (C) 2009, 2010, 2011, 2012 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License." 1 Introduction ************** This manual is an attempt to describe in detail the process of translating www.gnu.org articles--how to join a team, or start a new one, the responsibilities of the team members and leaders, as well as some peculiarities of the GNU Project's website when it comes to localization. The GNU website contains hundreds of documents, most of them philosophical articles (essays) and technical documents which need to be translated to make them available to a broader audience. This is especially important for the philosophy-related materials, as many people do not speak English and even those that do usually prefer to read such articles in their native language. Dealing with the task of translating a website this large is a hard job, and too often people volunteering as translators get frustrated or lose interest in keeping up with that work. Reading this manual, and the related GNUN manual (*note GNUnited Nations: (gnun)Top.), is just the tip of the iceberg. This is not meant to discourage any potential volunteer; rather, we prefer to be honest and to give preliminary estimation of the work/responsibility involved--if you feel you are not in a position to help you may move on to a smaller project before going through all procedures. It is important to realize that being a GNU Web Translator is a hard job at all levels, but your help is much appreciated and is invaluable contribution to the society. While there are many people who contribute to our community by writing free software (and their number is constantly increasing), the ones actively engaged in teaching others to appreciate and defend their freedom are only a few. Consequently and rather unfortunately, there are not so many volunteers willing to maintain on the long term translations of the various essays that describe the fundamental values of the free software movement. Translators of the `http://gnu.org' website are organized in language teams. Each team has one or more co-ordinators, who are responsible for the respective team. The co-ordinators participate in the Savannah `trans-coord' organizational project, which is managed by the GNU Web Translation Managers. The manual is organized in chapters that follow the organizational structure of the whole translation project. If you wish to join a translation team or contribute a translation or two, *note Members::. If your intention is to form a translation team, *note Leaders::. The chapter about the `trans-coord' administrators (a.k.a. "GNU Translation Managers") describes all the responsibilities and procedures involved in performing this duty. *Note Translation Managers::. 2 Team Members ************** Being a team member means to co-operate with a group of other people, working under the co-ordinatorship of the appointed team leader. Usually, this involves translating articles and reviewing/proof-reading other people's translations, participating in discussions about terminology issues, and sometimes performing clean-up tasks. 2.1 Joining A Team ================== To join a team, please first look at the existing teams at `http://www.gnu.org/server/standards/README.translations.html#TranslationsUnderway'. Chances are that there is already an established team. If there is no team listed for your language, this means that: * There is no team established and there are no translations to this language. * Some translations were submitted by occasional contributors, but no team has ever been formed. * The page is not updated to reflect the current situation (this shouldn't happen, but it's a possibility anyway). If the team is marked as "orphaned", there is no problem: you can still submit your translation to (*note Submitting::). In case you want to establish a new translation team or become a co-ordinator of an existing one, please refer to the next chapter, *note Leaders::. Contacting the team is best done via Savannah--each translation team has its own project, named `www-LANG', with the project page being . Usually teams have mailing lists, typically in the form . Some teams have homepages, with additional contact details and procedures for team members. You could also write directly to the team leader via the Savannah interface--that way your request will be recorded by Savannah and can be tracked or completed when the membership is approved. The actual process of submitting translations for review varies from team to team, as teams have certain liberties to organize themselves as they see fit. Thus, this manual does not make any attempt to cover that aspect--please refer to the team-specific documentation (if any) or ask the co-ordinator. Certainly, it is not mandatory to be an active team member to contribute a translation or two. If you feel that you don't have the time to participate actively, that is fine; you can still send your translation to the team. No contributions should be rejected. If you do not hear from the team within a reasonable time frame (say, two weeks), please write to . For general information about the translation process, *note Translation Tips::. 2.2 How To Submit a Translation =============================== Everyone can still submit translations even if there is no translation team formed. There are two ways to do that--following the existing procedures, which is the preferred way, and sending it as plain text, which means more work for a limited group of volunteers (the Translation Managers) to convert the translation in `.po' format. 2.2.1 How To Submit a Translation in PO Format ---------------------------------------------- All translations(1) are maintained via GNUN (see `http://www.gnu.org/software/gnun/'), which significantly eases maintenance and avoids the unpleasant situation where a translation is lagging behind the original. *Note Advantages: (gnun)Advantages. As of September 2008 all new translations at gnu.org are installed in `.po' format, and the `.html' is generated automatically. Here are the steps to produce and submit such a translation: * Make a checkout of the CVS Web repository of the `www' Savannah project. You can find generic instructions at `https://savannah.gnu.org/cvs/?group=www'. All updates to the website are done as commits in the repository, so you would need an up-to-date working copy. Anonymous access works under any circumstances, i.e. it is not mandatory to have a registered account at Savannah to use it. You can also check out only a specific directory, for example: cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/web/www co www/gnu This command will fetch only the `/gnu' directory--in other words, all articles at `http://gnu.org/gnu'. * Assuming you already know the article you want to translate, you have to create an empty `ARTICLE.LANG.po' file and then translate all messages with a PO editor. *Note New Translation: (gnun)New Translation. For an almost complete list of PO editors, *note PO Files: (gnun)PO Files. * When you are pleased with the translation, check that the PO file is valid and submit it to , attached to your message. The web-translators will review (to the best of their ability) the translation and will install it in the repository. * In order GNUN to be able to generate (and subsequently update) a gettextized translation, the language should have the server templates available as PO files. These templates are short, and translating them shouldn't take much time. If the language code is present in the `TEMPLATE_LINGUAS' variable at `server/gnun/gnun.mk', then you don't have to do anything. If it is not, the required files are `server/po/head-include-2.LANG.po', `server/po/body-include-1.LANG.po', `server/po/body-include-2.LANG.po' and `server/po/footer-text.LANG.po'--you can translate and submit them in the usual way, together with the translation of the essay. Additional templates are defined via the EXTRA-TEMPLATES variable in `server/gnun/gnun.mk'. If you don't want to translate the templates for whatever reason--do not worry, the web-translators will install empty templates (which means the English strings will be used). It is quite possible that there will be errors or typos, so once you are informed that the translation is online, check it carefully and if necessary, resubmit the PO file with corrections. Do not forget to run `cvs update' first and edit the updated `.po' file from the repository--most probably the Translation Managers have already made some modifications to it, usually to fix validation errors and to complete the PO file header. ---------- Footnotes ---------- (1) Well--not really, but the goal is to maintain all of them. 2.2.2 How To Submit a Translation as Plain Text ----------------------------------------------- If you feel the procedure described in the previous section is too burdensome and unfeasible for you to follow, you can still submit a translation in plain text. It will be manually converted to PO file by the GNU Web Translation Managers, which can be tricky sometimes, and naturally, means more work for them and slower processing of your request. You should _never_ translate the HTML markup--i.e. _do not_ use the "View Source" functionality of your browser to translate the raw HTML. Most of it is irrelevant, and automatically inherited from the markup of the original article. Simply save your translation in a plain text file (`.txt'), preferably in UTF-8 encoding. You can use any decent text editor for that--Emacs, Vim, gEdit, Kate, OpenOffice.org (the file should be saved as `.txt', not `.odt'), etc. Translate the title, the blue heading (if it differs slightly from the title) and the body of the article upto the link `back to top'. For example, for `http://www.gnu.org/philosophy/free-sw.html' that would be: The Free Software Definition - GNU Project - Free Software Foundation (FSF) We maintain this free software definition... ... ...If you would like to review the complete list of changes, you can do so on our cvsweb interface. Since web-translators do not speak all languages, it is essential to mark somehow any inner markup, because very often it is hard to figure out what translated text should be enclosed inside `' or `' elements, to name a few. The easiest way to do this is just to use the corresponding HTML markup, although anything else is suitable. For example, here is how to indicate that the link "History section" at the first paragraph of the same article should correspond to "seccio'n historial" in the translation: Si quisiera revisar los cambios que hemos hecho, por favor vea la {seccio'n historial} ma's abajo para ma's informacio'n. It is not necessary to include the value of the `href' attribute, as it is already known. If you wish your name to appear in the footer as a translator of the article, please also provide a translation of `Translation: YOUR NAME IN YOUR NATIVE LANGUAGE' or `Translated by: YOUR NAME IN YOUR NATIVE LANGUAGE', as you prefer. Please also state if you wish your email address to be published (some readers prefer to send suggestions directly to the translator, but we certainly do not require that translators must publish their address). Finally, send the translation to , either inline or as an attachment to your message. Once online, please check for any errors or omissions that may have resulted from the conversion process, and report them back. 2.3 Leaving A Team ================== When you realize that you don't have time or can't devote sufficient resources to perform the tasks anymore, it is prudent to inform the translation team co-ordinator and possibly all the rest of the team-mates. The team leader should always have a rough estimation about the available translators, even though there are no reliable means to establish that. Your announcement that you are stepping down (temporarily or permanently) may help her in this regard. 3 Team Co-ordinators ******************** A gnu.org translation team leader is the person who is ultimately responsible for organizing and managing the team, including, but not limited to, having the final say on contributed translations and exercising levels of control as she sees fit. A prospective team co-ordinator should have perfect understanding of the GNU Philosophy and the various issues the free software movement set out to solve. Energy and time are always needed, as well as certain communication skills. However, a team leader is not a dictator (for life); every action and/or decision taken should have its justification and should stem from the goals of the project at large. Inefficient or inoperative leaders are replaced, if necessary. 3.1 How To Form A New Team ========================== Establishing a new team is not hard, but a certain procedure ought to be followed. The most important thing to realize is that this is somewhat a long-term engagement that requires a lot of spare time, communication and technical skills, and devotion. The only "bonus" team leaders have is more work and more responsibilities. You should read most of the philosophy-related articles and _all_ the documentation related to the translation process before you decide to form a new team, or take over an orphaned team. Once you have the internal feeling that having a gnu.org translation team for your language is a must, and you are the one for this job, follow these steps: 1. If you do not have a Savannah account, register at `https://savannah.gnu.org/account/register.php'. Write access to the repository and project membership is handled via Savannah, so you would need an account in any case. 2. Checkout a complete working copy of the CVS Web repository as described at `https://savannah.gnu.org/cvs/?group=www'. If you still don't have a Savannah account or if you have registered one, but are not yet member of any Savannah project, refer to the instructions under "Anonymous CVS Access". If you are already a member of (any) Savannah project, you can proceed with "Project Member CVS Access via SSH", although you will still lack permission to commit (later, when it is granted, you can use the same working copy). Examine the layout and structure of the repository. Basically, it is mapped to the URL locations, more or less. Take a look at the most important materials to translate under `/philosophy', `/gnu', `/distros', `/copyleft' and `/licenses' directories just to get a rough estimate about the amount of work involved. If you are still not scared and determined to go on further, excellent. As you have probably observed, every directory that contains translatable articles has a `/po' sub-directory, which is where the new canonical source format of the translations is stored. 3. Assuming you have already read the GNUN manual entirely (as recommended in the beginning of this section), check if your language code is present in the variable `TEMPLATE_LINGUAS' at `server/gnun/gnun.mk'. If it is not, the first thing to do is to translate and submit to the following files (all in the `server/po/' directory): `head-include-2.LANG.po', `body-include-1.LANG.po', `body-include-2.LANG.po' and `footer-text.LANG.po', together with your first message stating that you would like to establish a new team. *Note New Translation: (gnun)New Translation. - The language code (LANG) should be the ISO 639-1 code of the language, for example `hy' for Armenian or `el' for Greek. If there is no such code, use the ISO 639-2 one--e.g. `mai' for Maithili. If the language is a variant such as Brazilian Portuguese or Simplified Chinese, use small caps and a dash--`pt-br' and `zh-cn' instead of `pt_BR' and `zh_CN'. - The PO file header and initial comments should be completed as documented. - Do not use HTML entities for non-ASCII characters as in the English original. They are harder to type and read. So, if there is `ü' and this is a character from the alphabet of your language, just write it as `u"' directly. 4. Any prospective team leader should submit a few translations first. This is a process of pointing errors and omissions (which are expected and natural); it's an important thing to do as the leader is going to carry out these checks on her own, once the team is approved. If there are existing translations that are not yet in PO format, the best thing to do is to migrate one or two. You can use `find' to find out what's already in the repository, for example: find -name \*.LANG.html 5. Submit at least two translations of your own. We maintain a list with priority articles at `http://www.gnu.org/server/standards/translations/priorities.html', although it is probably hard to start with one of them. Choose whatever you wish, provided it is an essay and not an auxiliary page. Avoid translating the homepage or `whatsnew.html'--they are moving targets and keeping up would be only a distraction for both parties in the process. As usual, send the completed translation to . 6. The Translation Managers will review your translations, and eventually comment on them (mostly technical details if there is no one among them speaking your language). Depending on the case, it might be required to submit a corrected file. In any event, please take into account the remarks in future work. 7. Once the Translation Managers determine that you are doing well and about to complete the process, they will send you the standard questionnaire for new team leaders. It is relevantly short and it shouldn't take more than 10-30 minutes to complete. This questionnaire is important, as we consider it crucial any translation team co-ordinator to have a good understanding of the philosophy of the free software movement. It is not unusual energetic people who complete all technical steps without trouble to fail here. 8. If all goes well, you will receive a response inviting you to apply for a new translation project at Savannah. The project name should be `www-LANG' where LANG is, unsurprisingly, the language code. If such a project already exists, this step will be skipped and you'll be made an administrator of the project. To register the project, go to `https://savannah.gnu.org/register/' and make sure you fill in the required fields. The "Group type" should be `www.gnu.org translation team', and "Project license"--`WebSite Only'. In the "Tarball URL" field enter a bogus URL such as `http://gnu.org'. *Pay attention:* This step is a formality. You should proceed with the project registration only when you have been asked by to do so. Otherwise, the submission may appear in the task list of the Savannah Hackers for a fairly long time, which is troublesome. 9. When the project is approved, the team information will be added to the list at `README.translations.html', you will become a member of the `www' project (thus granting you CVS write access to the whole repository--so be careful) and the `trans-coord' project. You'll also be subscribed to the following mailing lists: - www-commits - trans-coord-discuss You'll have to request subscription to `www-discuss' yourself--this list is managed by the GNU Webmasters, but all team leaders are required to subscribe in order to receive important site-wide announcements. The whole process should not take more than two weeks or maximum a month--if this period turns out to be longer, it is an indication that you do not have the required time and resources for this job, or web-translators are badly lagging behind and do not process the requests with the expected pace. Applications for new teams are sometimes processed in parallel(1)--the most suitable candidate is chosen in this case. This is, undoubtedly, based on a subjective judgment made by the Translation Managers, and many factors are important. The procedure for taking over an orphaned team is the same. Once completed, you will be made an admin of the respective `www-LANG' Savannah project, or if it doesn't exist, invited to apply for registration. Do not automatically remove old members just because you are starting "afresh"--some of them might want to continue to contribute. Contact them privately, explaining that you're the new appointed team co-ordinator, and ask them if they would be willing to continue their involvement in the team. ---------- Footnotes ---------- (1) In general, we try to avoid this and direct all new volunteers to the person who is already carrying out the process--this is also a verification if she can cooperate easily with others. 3.2 The Gentle Art of Managing A Translation Team ================================================= It is not our ambition to describe all activities involved in managing a team--it's very likely that you will encounter new problems, take care of tasks nobody else is aware of, or invent new techniques and approaches in your quest to keep things running. Managing a team is a hard task on all counts: communication with others, recruiting volunteers (and keeping them as long as possible), defending certain decisions, leading discussions about terminology issues, handling personal conflicts within the team, technical skills when reviewing/merging/syncing translations, etc. The list goes on and on. This manual can only summarize some of the most common issues and _suggest_ ways to deal with them. It is up to the team leader to establish the precise team procedures and practices. The mailing list was specifically created to discuss issues that leaders encounter while managing the teams, and for general organizational work. Feel free to discuss anything related to the translation process there. 3.2.1 Peer Review ----------------- First and foremost, find at least one person for peer review. You will review her translations, and she will review yours (at least in the beginning). Being a team leader does not mean that you cannot make mistakes; everyone does. The mutual review (especially if done by a larger group) is crucial for the quality of the translation process. Too many errors are just missed (especially if they are obvious) when the translator does a final review of her own translation. It is good to establish a practice: Do not commit officially (i.e. in `www', which will appear online at `http://gnu.org' immediately) a translation that is not yet reviewed by someone else who is not the translator. Always perform a final review yourself even if the translation has been checked by another member of the team. In other words, every translation installed at gnu.org should pass through your hands (read: eyes). One common technique for performing such reviews is to use a mailing list--the translator sends the new translation and participants comment on specific parts, quoting them appropriately. The benefit of this approach is that it is straightforward, but the drawback is that there is no automatic "record" about the conclusion of the specific discussion (or sub-thread) and sometimes such discussions easily digress, making it even harder to come up with a solution. Another way is to use Savannah's built-in trackers (the `Tasks' and `Bugs' trackers, specifically). This is further explained in the next section, *note Tracking Tasks::. One way or another, you should create some kind of review process. 3.2.1.1 How To Track Tasks and Bugs Using Savannah .................................................. The team leader has to make sure that prospective translations are reviewed, that they do not contain obvious errors and/or confusing expressions and that they match the spirit and intention of the original essay. However, many teams tend to suffer from a specific problem: team members rely on the leader to make these extensive reviews. That is fine, as far as it goes, and the leader should always review translations before installing them in the repository--but it is nearly impossible (especially for a large team) to rely on a single person for such tasks. Team co-ordinators often do not manage to make such reviews in time, resulting in frustration among the team members and generally slowing the translation process. A solution to this specific problem is to distribute the load among more people. For example: Member D makes a translation of `foo.html' and uploads `foo.LANG.po' in the translation project's repository at Savannah, marking the relevant task as "Ready for Test" (of course, the equivalent is sending a message with the attached translation to the team's mailing list, or similar). Then Member A, B and C (or only A and B if C is currently busy) review it independently and post comments/suggestions/errors in the bug tracker. Discussion goes on between them and D, problems are rectified and finally the leader (who may happen to be one of A, B, C, D) makes a final review. It is easier to make the final review when most of the issues are already fixed in previous revisions. Finally, the translation is published. The result is better quality of the translation (since more people looked at it) and the whole burden does not fall solely on the shoulders of the leader. You can also set up an internal formal rule: If a member makes a translation, he has to review another one (or two) as well. Some translations can take a fairly long time--the typical example is a complicated essay or a transcript of a speech. It is best to avoid duplicate work by indicating, or better--recording, that someone is working on this specific article. The `Tasks' tracker is suitable for this purpose. It is prudent to discuss the most convenient naming scheme and practice among team members, and publish the convention and/or rules at the team's homepage. Note that you can create "Custom Fields" in the trackers, and resolved bugs can be searched based on these custom values. Thus, a possible straightforward way to manage these tasks is: * If someone starts working on a new translation, she creates a new task with a `Subject' indicating the article, for example simply `philosophy/bsd.html' and assigns it to herself. * When the translation is finished and ready for review, the translator changes the `Status' to "Ready For Test". * Other members review it, and open bugs relevant to one specific problem. It is usually better not to conflate two different issues together--it makes them harder to discuss, and hard to track them by severity. Some are grammatical errors, some are fundamental ones that change the whole meaning, some are simply suggestions for improvement. It helps if the project admin creates new Category fields for every article, for instance `gnu/gnu-history.LANG.html', `philosophy/microsoft.LANG.html'--it would enable functionality like "Show me all bugs ever reported against this translation", which is useful. * Once the bugs (or at least the important bugs) are fixed, the team leader can make the final review and install the translation in the official repository, marking the task as `Done'. Bugs that are not resolved should remain opened, naturally. Of course, teams can choose to manage these things using external resources and eventually other bug (or issue) tracking systems. Whatever you decide, please make sure that bugs can be reported using free software only, and that the software providing that service is free. It makes an extremely bad impression if a reader has to report a problem about a gnu.org translation via non-free hosting platforms like SourceForge. If you use a certain facility (i.e. a bug tracking system) to manage bugs in translations, it is best to take advantage of `generic.LANG.html' and advertise it on every page. *Note generic.LANG.html: (gnun)generic.LANG.html, for details. 3.2.1.2 How To Proceed With Unreviewed Translations ................................................... Sometimes a translation (typically your own) is not reviewed by anyone else for a fairly long time. This is unfortunate, but there is no reason to keep it in draft state forever. If nobody reviewed it for a substantially long period (like 3 or 4 months), commit it as it is. Readers may report bugs as well (and they do!). It is important to record somehow that this published translation still lacks appropriate review. If the suggestion in the previous section is implemented, it would mean leaving the relevant task `Open' and `Ready For Test' despite the translation being officially online. You may also add a comment to the PO file. 3.2.2 CVS Commits And Best Practices ------------------------------------ As all team leaders have write access to the CVS repository of the `www' project, this technically means that they are able to modify every single file in it, and also those of the Web CVS repositories of other projects at Savannah. This vote of confidence should never be abused--the only files team co-ordinators should add/update are those relevant to their translation work. It is OK to fix an obvious typo in an original article; for anything else please report to . If you wish to volunteer as webmaster and help with generic webmaster work and RT tickets, that is perfectly fine--please follow the established (by the GNU Webmasters) procedure. If you are approved, you can modify such pages wearing your "webmaster's hat". If a particular page has issues with the markup which create problems for your language, please inform . For general issues that affect more articles, or for severe problems, please write to . It is recommended to read the entire CVS manual at least once, for a basic understanding of how this VCS works. *Note Concurrent Versions System: (cvs)Top. It is not necessary to become an expert--the `www' project does not use complex features like tags, vendor branches, merging, etc. as they are not very useful for a live website. However, you'd probably have to learn how to use CVS for effective work--to extract information from the history, review diffs and specific changes, synchronize with the working repository of the team (if any), adding/removing files, etc. If you make changes that affect more than one file but the change is coherent, please do it as a single commit. This will generate only one message to , which is better than 5 messages for 5 files about semantically the same change. Always write commit logs in English(1), providing a short description of the change. If you modify a file that is not an article but a script or part of software (such as `server/gnun/gnun.mk'), it would be nice to follow the GNU Coding Standards and describe the change precisely. For example, do not write: Added support for Nepali. or Yay! First commit of the Panjabi homepage! Instead, write the log as follows: (TEMPLATE_LINGUAS): Add `ne'. and (HOME_LINGUAS): Add `pa'. This makes it easier for others to search for a particular change in the history. If you add a binary file (for example, `.png'), do it with `cvs commit -kb FILE'. This turns off keyword substitution, which prevents RCS keywords like `$Id$' to get expanded, subsequently corrupting the file. *Note Substitution Modes: (cvs)Substitution Modes. More importantly, using `-kb' prevents corruption of the binary when people using CVS clients under Windoze checkout, modify the file, and then commit it with messed EOLs. (Unfortunately there are still committers using non-free operating systems--we cannot dictate what OS people use, but we can at least try to prevent damage.) Although not absolutely compulsory, it is recommended that every team leader subscribes to . It is useful to examine the diffs of your own messages, if you miss something while inspecting the diff before the commit. In any case, a team leader should be subscribed to that list to avoid his own commit messages to be moderated. If you absolutely do not desire receiving all traffic, just disable mail delivery in Mailman's user interface. ---------- Footnotes ---------- (1) This advice is applicable for the `www' repository only--feel free to write logs in your native language when committing in your project's Sources repository. 3.2.3 Taking Advantage of Savannah ---------------------------------- Every translation team should have a project in Savannah. There are some teams that use their own resources outside from Savannah; although there's no obligation to use Savannah for team work, the need for a Savannah project for each language is obvious: it's a standard way to find information for translation teams and their contacts. Using external hosting facilities may seem justified sometimes. Some teams may have already established repositories and/or bug tracking systems where usual contributors already have access. Some team members prefer to work within the established infrastructure of a broad translation team (for whatever reason), but this is discouraged. It is required that every team has a mailing list at Savannah (*note Savannah Mailing Lists::), because it is easier to pass its management to the new co-ordinator when the old one steps down, and it helps to keep the archives at one place for future members of the team. Likewise, it is better to use Savannah for the team's repository and bugs/tasks, but this is not mandatory. However, it is important to remember that regardless of the technical resources which a team decides to use, the responsibility of the team co-ordinator remains the same. Those teams that are using Savannah have a broad variety of tools at hand: team membership management, documents, trackers (bugs, tasks and support), alerts, CVS (and any other VCS that Savannah supports), home pages, etc. How each team uses these resources is up to the team itself, but it often turns out to choose Savannah for nearly all of the team activities, as it requires almost zero work; the Savannah Hackers are happy to support us. Whatever you (in your capacity as a team leader) decide, please do it with caution: some organizational decisions may become ineffective as time goes by, and some may not scale well when the team grows. If the team is young and has a couple of members, it is better to refrain from such decision and discuss them with all the members when their number grows. Two or three people do not need a rocket platform or complex wizardry to do their work. The next sections contain suggestions about how a team can use the facilities provided by Savannah. It is not mandatory to follow them, they are just suggestions. 3.2.3.1 Managing Members ........................ You should add active translators as members of the translation team, and remove them when they leave. Team members should have access to all of the project's resources, and tracking their number is one of the ways for web-translators to determine the status of the team. It is OK if a particular contributor wants to translate an article or two and does not want to be engaged with the team on a long-term basis. In such situations, there is no need to add her as a member. It is a good idea to mark inactive members, for example if there is no interaction (bug reports, new translations, updates to existing translations, proof-reading) for at least six months. You can do that by unmarking the `On Duty' checkbox for the respective project member under `Set Permissions'. Inactive members have absolutely the same rights as active ones--the only exception is that they don't count for the total number of members, and they appear separately on `View Members'. 3.2.3.2 Homepage of The Team ............................ Every Savannah project has a Web repository, which is, for technical and historical reasons, only CVS. By default it is mapped to ; to add files to it first make a checkout, following the instructions at . It is recommended to describe all team-specific procedures, if there are any. That way, you can point potential team members to the corresponding page containing these instructions, instead of repeatedly explaining every volunteer separately. All team-specific pages should follow the usual linking criteria (see `http://gnu.org/server/standards/README.webmastering.html#pollinking' and the FSF HTML Style Sheet Guidelines--`http://gnu.org/server/fsf-html-style-sheet.html'). For historical reasons, team-specific materials were available in the `www' repository, under ad-hoc locations as `/spanish', `/wwwsr', etc. These locations are deprecated, and the contents will be moved without warning to `/graveyard' in the `trans-coord' _Sources_ repository, following the original `www' layout (that is, if there were any sub-directories, they will be retained). 3.2.3.3 Support Tracker ....................... This tracker is supposed to be related to things about the _project management_ itself, i.e. project members may report here missing functionality and/or features that requires the project admin(s)'s action. Do not use it for anything else as it quickly becomes confusing. It is OK to disable it if the team is small. 3.2.3.4 Tasks Tracker ..................... This is a way to manage all sorts of tasks. They appear in the personal Savannah page of the assignee, so it is difficult to miss them out. It is possible to use this tracker to "announce" to the team members that a specific article should be translated. The one who volunteers may assign the task to herself. Teams may use this tracker to avoid duplicate work, by declaring that they intend to work on a specific translation. Feel free to organize the `Tasks' management as you see fit. 3.2.3.5 Bugs Tracker .................... The `Bugs' tracker is designed for tracking bugs. You can use for several purposes: * Suggest readers to report bugs there. * Use it for all kinds of internal team tasks. * Forward bugs reported against LANG translations in the `trans-coord' project and assign them to the specific maintainer (who is supposed to be a `www-LANG' project member), if you have such policy. 3.2.3.6 Patch Tracker ..................... This tracker doesn't make much sense for translation projects, as the original on which the translation is based is volatile and the translation "patch" is 100% guaranteed not to apply cleanly very soon after it is submitted. Even ignoring this detail, this specific feature is slowly marching towards complete deprecation, as there are much better ways to submit patches nowadays. You should disable this feature, as it causes only confusion. 3.2.3.7 News Tracker .................... That is a way to inform newcomers and interested people (who visit the project page from time to time, or subscribe to the `News' RSS feed) about a major change or event within the project. You can also setup news entries to be sent to a mailing list (that's possible for the other trackers as well). The purpose of this feature is informational--if members need to know about an important change (in practices, procedures, etc.), it is perfectly OK to announce it here. Some teams use it to announce new translations, which is also fine. 3.2.3.8 Managing Mailing Lists .............................. Every team should have a mailing list on lists.gnu.org and use it for internal communications. All active translators should be on the list. The list owner should be the co-ordinator of the team. The name of the list should begin with `www-LANG-'. The list will make it possible for the GNU project to contact the team when the co-ordinator disappears; its archive will also give access to the history for new translators. You can create new mailing lists via the Savannah interface. However, this should be done after some thought. If the project membership is low (<= 10 members), there is no need to create more than one mailing list. You can redirect all messages generated by the trackers to any list. 3.2.3.9 Version Control Systems ............................... An easy way to keep up with changes in the original articles and to manage continuous contributions is to keep all translations in the translation project's Sources repository. That way, it is easy to edit draft translations and install them in `www' only when they're ready. It is also convenient to update the translation (merge any changes from the original) while it is still under review. *Note PO Files and Team: (gnun)PO Files and Team, for more information. *Remember:* A choice of a particular VCS is a sensitive matter--some modern ones provide compelling features, but they also bump the barrier for participation higher. The VCS is supposed to ease collaborative maintenance--if it eases only you, project members just won't use so that won't be a net win. Web-based Systems ................. An alternative way to maintain translations is to use one of the existing online editors. There are plans to install a web-based system for managing `.po' files at Savannah, including online editing and statistics. Until it happens, teams who wish to use this functionality may setup such a server on a host of their own, or use one of the existing free hosting platforms such as Launchpad (`http://translations.launchpad.net'). Here is a short and probably incomplete list of such systems: * Pootle--`http://translate.sourceforge.net/wiki/pootle' * Vertaal--`http://code.google.com/p/vertaal' * Narro--`http://code.google.com/p/narro' * Launchpad--`https://dev.launchpad.net' If you decide to use such a system, please make sure that no translations are published in HTML format there. Note that to keep the `.pot' files regularly updated (assuming such a web-based system runs `msgmerge' automatically), you'll have to take care of the one-way regular sync from the `www' CVS repository. 3.2.4 Promoting Members As Co-leaders ------------------------------------- When the team grows large and it becomes hard for a single person to manage, there is no problem to add another (or even another two) people to help. Note that a subsequently appointed team co-ordinator is not simply a "committer" with write access to the `www' repository; she has full responsibilities just like a single leader, although the latter still remains the primary contact for the team. If you'd like another person to act as a co-leader and help you with the management tasks, send a message to with her name and Savannah account. She has to be already a member of `www-LANG'. The procedure for co-leaders is a simplified version of the one for a new team or taking over an existing team. *Note New Team::. To remove co-ordinators, please write to with details and rationale for the removal. Do not edit `README.translations.html' yourself; this is a final formality step to be performed by the Translation Managers. 3.3 Reporting Team Status ========================= Team leaders must send an annual report about the status of the team. A good report should include: * General information about the team's accomplishments during the past year, like: - A list of new translations. - New members since the last report. - Current active members. - Solved problems and other issues, if any. (Usual bug reports and other improvements/fixes to the existing translations do not count as "problems" in this sense.) * Current problems (technical or social), conflicts, and ideas for sorting them out. * Anything else you consider important or worth mentioning. The best time to send a report is near the end of the year, for example November. In any case, please do not send it later than December 15th, as the Translation Manager has to prepare a general report to the FSF, and it is better if it takes into account the reports of the team leaders. If there is no sensitive information in the report and you feel like sharing it, you can send it to (which is still a private mailing list). That way, other list readers may help with suggestions how to solve a particular issue. Informing each other about the progress improves the community spirit. If you do not wish to share some information that is in the report, please send it to . 3.4 How To Retire Painlessly ============================ When you feel you don't have the energy to manage the team successfully, or perhaps you start losing motivation, please inform . It would be substantially easier if you try to find a replacement or recommend a specific person--we will try to find someone in any case, but your judgment is important and it will be considered with priority. An excellent way to step down is to do it with a "plan"--suggest the person you consider capable of doing the job as co-leader (*note Co-leaders::) and retire completely when she is absolutely ready to proceed without your further help and advice. 4 `trans-coord' Admins ********************** This chapter is not yet written. The current admins know what to do, hopefully. 5 Details About The Translation Process *************************************** The purpose of this chapter is to summarize some odd and not so obvious details about specific parts of the gnu.org website. Most of them become well known as time goes by; however, practice shows that it is difficult to figure them out at once. Some limitations and oddities are just historical remnants from old habits and previous incarnations of old (inefficient) translation and webmastering processes. Others are outright deficiencies (i.e. "bugs"), but no one has stepped in to correct them so far. 5.1 Migration To The New Style ============================== Migration to the new style should be straightforward, and this is one of the problems GNUN set out to solve. If you have to migrate old-style translations, *note Migrating: (gnun)Migrating. If the old translation is HTML 2.0 (or 3.2), you still have to take care about the inner markup. Overall, it is substantially easier than doing all of it manually. Subsequent migrations to newer HTML standards and newer look and feel of the website are supposed to happen semi-automatically, although this manual will be updated as needed. 5.2 Summary of SSI `#include's ============================== The GNU Project's website uses SSI (Server Side Includes) to manage some common parts that are the same in many of the articles. With the help of GNUN their handling should be behind the scenes, but for some of them manual intervention is needed. Here is a (possibly incomplete) list of the `#include''s used: `server/banner.html' This file contains only `#include' directives, so the "translation" should be identical, with filenames modified to have the LANG extension. `server/body-include-1.html' Contains the top menu with useful "skip to" links. `server/body-include-2.html' This is the file containing the menus, the FSF widget, and any visible announcements made from time to time. If a string gets "fuzzy" or "new" here, it will appear in English in all translations, until `server/po/body-include-2.LANG.po' is updated. Note that some validation errors originate from an error in `server/body-include-2.LANG.html' or some other template file. `server/footer-text.html' This is a very short file currently containing the "back to top" link. Also translatable via GNUN. `server/header.html' The declaration that is included in literally every file. It is maintained manually, as it does not make much sense to put it under GNUN's control (there are no translatable strings). Remember to specify the proper `xml:lang' and `lang' attributes, and for RTL languages, the `dir' attribute. For example, the file `header.ar.html' should contain this line: `server/head-include-1.html' This file (included from `server/header.html') is very important: the encoding is defined here. Note that it is applicable for all translations, so it is not possible to have different articles in different encodings. Even if a specific PO file is deliberately encoded in another encoding, the generated HTML will contain the encoding declared in the `' element at `server/head-include-1.LANG.html', so browsers will obey it. The encoding should be UTF-8. This is required because the English text in the articles serves as a replacement of the translation when the latter is not complete, and because all translated pages share automatically generated lists of translations. `server/html5-header.html' This file is included in newer pages using some entities introduced in HTML5 draft. We have to distinguish those pages since some features of HTML4 were rejected in HTML5, and our old pages don't validate as HTML5. `server/html5-head-include-1.html' Likewise, this file replaces head-include-1.html for HTML5 pages. `server/head-include-2.html' Imports the standard CSS, which can be overriden. *Note CSS::. `server/footer.html' This is a very short and simple file (at least at the time of writing), containing another `#include' directive. It is maintained manually, so just add LANG to the filename, in order the localized `footer-text.LANG.html' to be included. `server/outdated.html' This file is automatically included in outdated translations. It contains respective message with links to the English file and to a generated difference of the current revision of the English file against the most recent revision that has a complete translation. It is only included in articles affected by "grace period" because in those cases the outdated passages are replaced with English text, and it is evident without any notices that there is no complete and up to date translation. `translations.include' The list of translations for the homepage (and only the homepage). It is maintained manually; in order the link to a translation to appear on all of the homepages, it has to be present here. `gnusflashes.include' A portion of the most recent 3 news items from `server/whatsnew.html', generated automatically. If your language does not have `server/po/whatsnew.LANG.po', this file will be used. Otherwise, if there is an existing localized homepage and you commit `whatsnew.LANG.po', the homepage will be rebuilt to include the translated `gnusflashes.LANG.include'. `server/whatsnew.include' Generated automatically, this file is included from `server/whatsnew.html'. Translations are built automatically, and the localized `gnusflashes.include' is derived from it. `licenses/gpl-3.0-body.html' `licenses/fdl-1.3-body.html' `...' Some of the licenses have the text of the license itself separated in another file. This serves two purposes: 1) to provide a "standalone" HTML version of the license without the gnu.org style; 2) to prevent strings sneaking in the `.pot' files, as licenses have only unofficial translations, hosted elsewhere. Nothing special should be done about these SSI directives; the files generated by GNUN include them verbatim as they should not be translated. `server/sidebar*.html' These files are deprecated--they are remnants from an older design that lived shortly in the middle between the old classic design and the current one. If all translations are successfully migrated and none of them includes such files, you should delete them. You can use `grep' to check this. The files - `header.html' - `head-include-1.html' - `html5-header.html' - `html5-head-include-1.html' - `head-include-2.html' - `banner.html' - `body-include-1.html' - `body-include-2.html' - `footer.html' - `footer-text.html' in the `server' sub-directory are what webmasters call "the server templates". These files are included in almost every article, translated or not. They are somewhat important, as an error made in translating them propagates everywhere. The server templates, the homepages, and whatsnew (a.k.a. "GNU News") are being rebuilt by GNUN whenever there is a change in the original English files; the `GRACE' variable has no effect for them. *Note Runtime Variables: (gnun)Runtime Variables. 5.3 How To Use Custom CSS ========================= The file `style.css' gets included in almost all the English articles. It includes two other files, which form the actual CSS style used. However, this style is seldom right for translations--many languages have much longer expressions, and that is natural. To include your own CSS, create a file `style.LANG.css' and add it _after_ the original `style.css' in your `server/po/head-include-2.LANG.po', i.e. # type: style msgid "@import url('/style.css');" msgstr "" "@import url('/style.css');\n" "@import url('/style.bg.css');" Override only what is necessary and looks broken in your language; do not invent your own style. This is important for the consistency of the gnu.org website. A typical language-specific `style.LANG.css' file looks like this: .inner { max-width: 65em; } #logo{background:url(/graphics/topbanner.bg.png) no-repeat;} #fssbox {font-size: 50%;} This widens the menu and the area where the articles are displayed (because the menu entries are _much_ longer than the English equivalents when translated), includes a localized logo, and makes the font size for the FSF widget twice smaller (because in this language, the translations are almost twice longer and displayed truncated, which is undesirable). When creating your own `style.LANG.css', don't forget to include the license notice from the `style.css', with a short comment. If using the default CSS style for translations does not give the expected good results, or there are other problems (significant or not) that obstruct reading and/or worsen the look from aesthetic point of view, please write to with a description of the issue. If there are several unrelated problems, send separate messages with appropriate explanation (which may include a demonstration of the bug, such as a screenshot). 5.3.1 Localizing The `topbanner' Image -------------------------------------- If you'd like the nice gnu image to be localized (i.e. "GNU Operating System" to appear in your native language, here are the steps: 1. Copy `graphics/topbanner.svg' as `graphics/topbanner.LANG.svg' where LANG is the language code, as usual. Edit the file with Inkscape or with a plain text editor such as GNU Emacs, translating "GNU Operating System". Then with Inkscape, save the file as `graphics/topbanner.LANG.png' (File -> Export Bitmap...). Then open the PNG image with the GIMP and flatten it (Image -> Flatten Image). Don't forget to save and `cvs add' the files(1). 2. Create a `style.LANG.css' at the toplevel directory, if it doesn't exist already. Normally, you would need only one line in it, namely: #logo{background:url(/graphics/topbanner.LANG.png) no-repeat;} 3. If not done already for other reasons, update `head-include-2.LANG.po' to include the language specific `style.LANG.css'. *Note CSS::. If you feel uncomfortable manipulating images--don't despair! Send a plea for help to , some people would be happy to help you. Failing that, write to . ---------- Footnotes ---------- (1) This advice applies to all new files, of course. 5.3.2 Specific Issues Related to RTL ------------------------------------ Unfortunately, the `http://gnu.org' website does not have excellent support for RTL (right-to-left) languages, although best efforts are made. If your language is in this category, make sure to: * Set the attribute `dir="rtl"' in the `html' element at `server/header.LANG.html'. * You _must_ have a custom CSS to override some of the pre-defined values. See `style.ar.css' and `style.fa.css' to understand how these two languages solve some of the problems. *Note CSS::. *Important:* Some articles contain their own `