path: root/greek/devel/website/translating.wml

#use wml::debian::template title="Translating Debian web pages" BARETITLE=true
#use wml::fmt::verbatim
#use wml::debian::translation-check translation="8627b3f6f68ecae195c89923923955f8e32ea092" maintainer="galaxico"

<p>To make the job of the translators as easy as possible the pages are
generated a bit differently than many of you will be used to. The web pages
are actually generated using source that is marked up with
<a href="https://www.shlomifish.org/open-source/projects/website-meta-language/"><tt>wml</tt></a>.
There are separate directories for each language.
</p>

<p>If you plan to start an entirely new translation of the Debian web site,
please see the <a href="#completenew">section on starting a new
translation</a>.
</p>

<h2><a name="singlepages">Translating individual pages</a></h2>

<p>We use WML to separate the specific content of a page from the elements
common to multiple pages. This means that one needs to edit certain WML
source files instead of HTML files. Please <a href="using_git">use Git</a>
to acquire the current sources.  You'll need to check out at least two
directories: <tt>webwml/english/</tt> and <tt>webwml/<var>&lt;language&gt;</var>/</tt>.</p>

<p>To translate a single page from English into your language, the original
.wml file needs to be translated and placed within the other language's
directory. The relative path and name need to be the same as in the English
directory in order for the links to continue to work.</p>

<h3>Translation headers</h3>
<p>It is strongly
recommended that the translator adds an additional line to the headers
after the last <code>#use</code> statement to record the exact commit of
the original file that was translated, so that <a href="uptodate">updating is
easier</a>. The line looks like this:
<kbd>#use wml::debian::translation-check translation="<var>&lt;git_commit_hash&gt;</var>"</kbd>
Please note that if you generate the translatable file using <tt>copypage.pl</tt>
tool (which is highly recommended), the git commit hash will be generated
automatically. The usage of <tt>copypage.pl</tt> will be explained in the
following texts.
</p>

<p>Some translation teams also use this line to mark the official
translator of each web page. Doing so, you will get automatic mails
when the pages you maintain are updated in English, and need your
attention to update the translation. For that, simply add your name as
maintainer at the end of the <code>#use</code> line to make it look
like this:
<kbd>#use wml::debian::translation-check translation="<var>git_commit_hash</var>" maintainer="<var>your name</var>"</kbd>.
The <tt>copypage.pl</tt> will do this automatically 
if you set the <tt>DWWW_MAINT</tt> environment variable
or use the <tt>-m</tt> command-line switch.
</p>

# I Removed cvs specific descriptions from here because of cvs to git transition.
# Help to update instruction if possible.
#
#<p>You also need to explain to the robot who you are, how often you
#want to get automatic mails and their content. For that, edit (or let
#your coordinator edit) the file
#webwml/<var>language</var>/international/<var>language</var>/translator.db.pl
#in the repository.  The syntax should be quite understandable, and you can
##use the file of the French team as template if it does not exist for
#your language yet. The robot can send several kinds of information, and
#for each of them, you can choose the frequency at which it will be
#sent to you. The different kinds of information are:
#</p>

#<ul>
# <li><b>summary</b>:  a summary of which documents are outdated</li>
# <li><b>logs</b>: the "cvs log" between the translated and current versions</li>
# <li><b>diff</b>: "cvs diff"</li>
# <li><b>tdiff</b>: the script will try to find the part of the translated text modified by the English patch</li>
# <li><b>file</b>: add the current version of the file to translate</li>
#</ul>

#<p>Then, for each of them, the value should be one of: 0 (never), 1 (monthly), 2 (weekly) or 3 (daily).</p>

#<p>An example could be:
#</p>

#<verbatim>
#                'Martin Quinson' => {
#                        email       => 'martin.quinson@tuxfamily.org',
#                        summary     => 3,
#                        logs        => 3,
#                        diff        => 3,
#                        tdiff       => 0,
#                        file        => 0
#                },
#</verbatim>

<p>The header of the web page can be easily produced by using the
<tt>copypage.pl</tt> script in the webwml root directory. The script
will copy the page to the right place, create directories and
makefiles if necessary, and add the required header automatically.
You will be warned if a page to be copied exists in the repository, whether
because the page was removed from the repository (due to it being
too out of date) or because somebody already committed a translation
and your local repository copy is not up to date.
</p>

<p>In order to start using the <tt>copypage.pl</tt> you should first
configure the file <tt>language.conf</tt> in the <tt>webwml</tt> root directory,
which it will use to
determine the language you are translating to. That file needs up to
two lines: the first line gets the language name (like <tt>german</tt>) and
the second can optionally get the name of the maintaining translator. You can also
set the language through the use of the <tt>DWWW_LANG</tt> environment
variable and use the <tt>DWWW_MAINT</tt> environment variable to
put your name so that it will be added to the header of the wml
files generated as the maintainer for the translation. Or as a third possibility,
you can give language and (optionally) maintainer on the commandline via
<tt>-l german -m "Donald Duck"</tt> and not use the language.conf file at all.
There are other features
available in the script, just run it without any arguments to get the help.
</p>

<p>After you have run e.g. <kbd>./copypage.pl <var>file</var>.wml</kbd>,
translate the original text within the file. Comments in files will indicate
if there are items that should not be translated; respect them. Don't do any
unnecessary changes to the formatting; if something needs to be fixed, it
should likely be done in the original file.</p>

<h3>Page building and publishing</h3>

<p>Since we use <a href="content_negotiation">content negotiation</a>,
HTML files are not named <tt><var>file</var>.html</tt> but
<tt><var>file</var>.<var>&lt;lang&gt;</var>.html</tt>, where <var>&lt;lang&gt;</var>
is the two letter code of the language, according to
<a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO 639</a>
(e.g. <tt>fr</tt> for French).</p>

<p>You can build HTML from WML by running
<kbd>make <var>file</var>.<var>&lt;lang&gt;</var>.html</kbd>.
If that works, check if the syntax is fully valid with
<kbd>weblint <var>file</var>.<var>&lt;lang&gt;</var>.html</kbd>.</p>

<p>NOTE: The web pages are regularly rebuilt automatically on the
www-master server, based on the wml source in git. This process is for
the most part impervious to errors. However, if you commit a broken
file in the top level of your translation (e.g. the top-level
index.wml file), it will break the build process and stall all the
other updates to the web site. Please pay special attention to these
files.</p>

<p>Once the page is good to go, you can commit it into Git. If you
have the permissions to do this yourself, please push the commits to
the <a href="https://salsa.debian.org/webmaster-team/webwml">webwml
git repository</a>; if not, send it to <a
href="translation_coordinators"> somebody with write access to the
repository</a>.</p>

<h2><a name="completenew">Starting a new translation</a></h2>

<p>If you would like to start translation of the Debian web pages into
a new language, send us e-mail (in English) at
<a href="mailto:webmaster@debian.org">webmaster@debian.org</a>.

<p>First of all, clone our source tree, as described <a
href="using_git">on our Git introduction page</a>.</p>

<p>After you have a git checkout, start by creating a new top level
directory for your translation, next to english/ and others. The name
of the translation directory must be in English and entirely lowercase
(e.g. "german", not "Deutsch").</p>

<p>Copy the <tt>Make.lang</tt> and <tt>.wmlrc</tt> files from the english/
directory to the new translation directory. These files are essential for
building your translation from WML files. They have been designed so that
after you copy them to the new language directory, you only have to change
these things:</p>

<ol>
  <li>The variable LANGUAGE must be changed in the file <tt>Make.lang</tt>.

  <li>The variables CUR_LANG, CUR_ISO_LANG and CHARSET must be changed in
      the <tt>.wmlrc</tt> file. Add CUR_LOCALE to that, if you need it for
      sorting.

  <li>Some languages may need extra processing to handle the charset. This
      can be done using the --prolog and --epilog options to wml. Use the
      WMLPROLOG and WMLEPILOG variables in <tt>Make.lang</tt> to do this.

  <li>The variable LANGUAGES must be changed in top-level
      <tt>webwml/Makefile</tt> file so that your language will get built
      along with the other ones, on www.debian.org. We would prefer if you
      left this particular change up to the webmasters, because you may not
      be aware that your translation is broken when checked out of VCS
      afresh, which could break the building process of the rest of our web
      site.
</ol>

<p>After that is done, put the following line in a new file called
"Makefile" in that directory:

<pre>
<protect>include $(subst webwml/<var>yourlanguagedir</var>,webwml/english,$(CURDIR))/Makefile</protect>
</pre>

<p>(Replace <var>yourlanguagedir</var> with the name of your language's
directory, of course.)</p>

<p>Now create a subdirectory inside your language's directory called "po",
and copy the same Makefile to that subdirectory (<kbd>cp ../Makefile .</kbd>).
</p>

<p>In the po/ directory, run <kbd>make init-po</kbd> to generate the initial
set of *.po files.</p>

<p>Now that you have the skeleton set up, you can start
adding your translations in our shared WML tags used in templates.
The first templates that you should translate are those that appear
on all of the web pages, like the header keywords, the entries in the
navigation bar, and the footer.</p>

# The page on <a href="using_wml">using WML</a> has more information on this.

<p>Start translating in the <code>po/templates.<var>xy</var>.po</code> file
(where <var>xy</var> is your language's two-letter code). For every
<code>msgid "<var>something</var>"</code> there is initially a
<code>msgstr ""</code> where you should fill in the translation of
<var>something</var> in the double quotes after <code>msgstr</code>.</p>

<p>You don't have to translate all of the strings in all of the .po files,
just those that your currently translated pages actually need. To see if you
need to translate a string, see the comments in the .po file just above each
<code>msgid</code> statement. If the referenced file is in
<tt>english/template/debian</tt>, then you should most likely translate it.
If not, you can postpone it for later, when you actually translate the
relevant section of the web pages that require it.</p>

<p>The point of po/ files is to make things easier for translators, so that
they (almost) never have to edit anything in the
<tt>english/template/debian</tt> directory itself.
If you find anything to be wrong with the way something
is set up in the template directory, please make sure that the problem is
fixed in a general manner (feel free to ask someone else to do it for you),
rather than commiting actual translations into the templates, which would
(usually) be a major problem.</p>

<p>If you aren't sure if you did something properly, ask on the debian-www
mailing list before committing.</p>

<p>Note: if you find you need to make any other changes, send mail to
debian-www saying what you changed and why, so the problem can be corrected.

<p>After the template skeleton is done, you can start with translating the
front page and the other *.wml files. For a list of files that
should be translated first, check <a href="translation_hints">the hints
page</a>. Translate *.wml pages as described <a href="#singlepages">at
the top of this page</a>.</p>

<h3>Reviving outdated translations</h3>

<p>As described in <a href="uptodate">how to keep translations up to date</a>,
outdated translations of the website might be removed automatically when a
long period of time has gone by without an update.</p>

<p>If you find that some files got removed sometime in the past and you would
like to checkout the file again for further editing, you may search through
the commit history using git's standard commands.</p>

<p>For example, if the delete file is "deleted.wml", you may search the history
by running:</p>

<verbatim>
   git log --all --full-history -- <path/to/file/deleted.wml>
</verbatim>

<p>You may find out the exact commit that removed the file you want, together
with the commit's hash string. To display the detail information about the
modification made to the file in this commit, you may
use <code>git show</code> subcommand:</p>

<verbatim>
  git show <COMMIT_HASH_STRING> -- <path/to/file/deleted.wml>
</verbatim>

<p>If the commit is exactly the one that deleted the file, you may restore
the file to the workspace using <code>git checkout</code>:</p>

<verbatim>
  git checkout <COMMIT_HASH_STRING>^ -- <path/to/file/deleted.wml>
</verbatim>

<p>Once you do this you have to, of course, update the document before
you check it in again. Or it might be otherwise removed.</p>


<h3>The rest of the story</h3>

<p>The description above will probably be enough to get you started.
Afterwards, you will want to refer to the following documents which provide
more detailed explanations and additional useful information.</p>

<ul>
<li>A number of <a href="examples">examples</a> are provided to give you
    a clearer idea of how to get started.
<li>A number of common questions are answered and helpful hints provided in
    the <a href="translation_hints">translation hints</a> page.
<li>We have mechanisms in place to aid in <a href="uptodate">keeping the
    translations up to date</a>.
<li>To see the status of your translation and how it compares to others,
    check the <a href="stats/">statistics</a>.
</ul>

<P>We hope you find the work we've done will make translating
the pages as easy as possible. As has already been mentioned, if
you have any questions, you can ask them on the <a
href="mailto:debian-www@lists.debian.org">debian-www</a> mailing
list.