Update of /cvsroot/fink/experimental/alexkhansen/xml/multilingual
In directory
sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv22744/experimental/alexkhansen/xml/multilingual
Added Files:
Makefile multilingual.xml
Log Message:
committing multilingual howto doc to experimental tree for general
edification
--- NEW FILE: Makefile ---
# $Id: Makefile,v 1.1 2004/03/04 02:17:05 alexkhansen Exp $
# process XML files with stylesheet to produce HTML
basedir = ..
SOURCE = multilingual.xml
#TARGET = index.php intro.php install.php upgrade.php packages.php conf.php usage.php
header.inc
TARGET = index.php intro.php files.php header.inc
WANT_HTML = 1
DESTDIR = doc/multilingual
include $(basedir)/Makefile.common
# eof
--- NEW FILE: multilingual.xml ---
<?xml version = '1.0' encoding = 'iso-8859-1'?>
<!DOCTYPE document SYSTEM "../finkdoc.dtd">
<document lang="en" filename="index" >
<title>Fink Internationalization (i18n) Howto Guide</title>
<shorttitle>i18n</shorttitle>
<cvsid>$Id: multilingual.xml,v 1.1 2004/03/04 02:17:05 alexkhansen Exp $</cvsid>
<preface>
<p>
<em>This document is under construction.</em>
</p>
<p>Welcome to the Fink Website Internationalization Howto.
This document is intended to offer guidelines for people who want
to contribute to the i18n effort for the Fink website.</p>
</preface>
<chapter filename="intro" >
<title>Introduction</title>
<shorttitle>Intro</shorttitle>
<section name="what" >
<title>What is going on with internationalization of the Fink website?</title>
<p>The Fink project has undertaken an effort to add full internationalization
support to its website, in order to make the site more accessible
worldwide. Thanks to Baba Yoshihiko, there is now a framework in
which pages in multiple languages can be employed
</p>
</section>
<section name="languages" >
<title>Languages</title>
<p>We currently have volunteers working on the following languages:
</p>
<ul>
<li>Danish</li>
<li>Dutch</li>
<li>English (the baseline documentation)</li>
<li>French</li>
<li>German</li>
<li>Italian</li>
<li>Japanese</li>
<li>Spanish</li>
<li>Simplified Chinese</li>
</ul>
</section>
<section name="organization" >
<title>Organization</title>
<p>The Fink I18n team is organized as follows.</p>
</section>
<section name="helping" >
<title>Helping out.</title>
<p>If you wish to help out with the internationalization effort, there are
several things that you can do:
</p>
<ul>
<li>Join discussions on the fink-i18n mailing list. This is where we will
discuss the mechanics of internationalization, announcements of updates to documents
will be made, etc.
</li>
<li>Look over the translation for your own language. You may have a
translation that flows better than does the official one, you may find a translation
error, and other possibilities.</li>
<li>Become a translator yourself. If your language isn't currently represented
(or even if it is), and you think you can provide an effective translation, then you
may want to volunteer to be a translator for your language.
<p>Be advised, however, if you are the first person to work on your language:
there are quite a few documents that you will have to translate initially. Once this
is done, there typically will be small changes made.</p>
<p>To be a translator you need to:</p>
<ol>
<li>Register for an account at SourceForge.</li>
<li>Send a message to the fink-18n mailing list, letting them
know your SourceForge username. Somebody there will make the arrangements
for you to have CVS access to the documentation section.</li>
</ol>
</li>
</ul>
</section>
</chapter>
<chapter filename="files" >
<title>The Documentation Files</title>
<shorttitle>Files</shorttitle>
<section name="file-standards" >
<title>File Standards</title>
<p>There are two different file standards you will have to be concerned with as
a translator:</p>
<ol>
<li>
<em>Static (PHP only)</em>
<p>These are documents whose organization (e.g. item numbering) isn't
expected to change much on a day-to-day basis. In this case the document just has a
PHP file, which you will translate.</p>
</li>
<li>
<em>Dynamic (XML generates PHP and HTML)</em>
<p>These documents (e.g. the FAQ) are updated and restructured more often,
so they need the facility to be reorganized dynamically. Such documents use an XML
file as the basis by which PHP and HTML files are generated, via a script. As a
translator, your responsibility is to translate the XML file.</p>
</li>
</ol>
</section>
<section name="acquiring" >
<title>Acquiring Files to Work on.</title>
<p>
For now, you must check out the xml branch of the web site:</p>
<ol>
<li>
Open a terminal</li>
<li>Create a directory somewhere to contain the Fink web branch:
<codeblock>mkdir -p <em>fullpathofthedirectory</em>
</codeblock>
</li>
<li>
Move to that directory:
<codeblock>cd fullpathofthedirectory</codeblock>
</li>
<li>
Set the cvs environment variable.
For <filename>bash</filename> and <filename>zsh</filename>:
<codeblock>export CVS_RSH=ssh</codeblock>
For <filename>tcsh</filename>:
<codeblock>setenv CVS_RSH ssh</codeblock>
</li>
<li>
Login to cvs.sourceforge.net:
<codeblock>cvs -d:pserver:[EMAIL PROTECTED]:/cvsroot/fink login</codeblock>
</li>
<li>
Push the enter key (no password, anonymous as default)
</li>
<li>
Check out the xml module (for example):
<codeblock>cvs -z3 -d:pserver:[EMAIL PROTECTED]:/cvsroot/fink co
web/xml</codeblock>
</li>
</ol>
</section>
<section name="initial-translation" >
<title>Initial Translation</title>
<p>The files to translate, in order of priority, are:
</p>
<p>
<strong>Title</strong> (English version file)</p>
<ol>
<li>Constants file (<filename>web/xml/web/constants.*.inc</filename>)(see
below)</li>
<li>User's Guide (<filename>web/xml/uguide.xml</filename>)</li>
<li>FAQ (<filename>web/xml/faq.xml</filename>)</li>
<li>Running X11 (<filename>web/xml/x11/x11.xml</filename>)</li>
<li>Document Index (<filename>web/xml/doc/doc.xml</filename>, but the PHP
files for this cannot be generated by running <code>make</code> due to remaining xslt
problems)</li>
<li>Packaging (<filename>web/xml/packaging/packaging.xml</filename>)</li>
<li>Porting (<filename>web/xml/porting/porting.xml</filename>)</li>
<li>News (<filename>web/xml/news/news.xml</filename>)</li>
</ol>
<p>The <filename>constants.*.inc</filename> files are intended to deal with hard
coded items in the PHP include files. They are mostly menu items and such, located on
top and left of the pages. You should separate them from the scripts and create a
file like the sample file (English) below:</p>
<codeblock>
/* The Sections. Used in Menu Navigation Bar */
define (FINK_SECTION_HOME, 'Home');
define (FINK_SECTION_DOWNLOAD, 'Download');
define (FINK_SECTION_PACKAGE, 'Packages');
define (FINK_SECTION_HELP, 'Help');
define (FINK_SECTION_FAQ, 'F.A.Q.');
define (FINK_SECTION_DOCUMENTATION, 'Documentation');
define (FINK_SECTION_MAILING_LISTS, 'Mailing Lists');
/* The Home Subsections. Used in Menu Navigation Bar */
define (FINK_SECTION_HOME_INDEX, 'Index');
define (FINK_SECTION_HOME_NEWS, 'News');
define (FINK_SECTION_HOME_ABOUT, 'About');
define (FINK_SECTION_HOME_CONTRIBUTORS, 'Contributors');
define (FINK_SECTION_HOME_LINKS, 'Links');
/* The word 'Sections'. Used in Menu Navigation Bar */
define (FINK_SECTIONS, 'Sections');
/* Contents as Table of Contents. Used in FAQ/Documentation Sections */
define (FINK_CONTENTS, 'Contents');
</codeblock>
<p>When you translate, you normally follow the steps as below (suppose you
are translating the <strong>Running X11</strong> document into French):</p>
<ol>
<li>Copy the xml file
<codeblock>cp x11.xml x11.fr.xml</codeblock>
</li>
<li>Edit the line to declare it is French and its encoding is UTF-8
<codeblock><?xml version='1.0' encoding='utf-8' ?>
...
<document filename="index" lang="fr" >
...</codeblock>
</li>
<li>Save as UTF-8
Be aware that the encoding must be utf-8 and take care not to change
anything but true text.</li>
<li>Once you are done, or just to test it, edit the <code>Makefile</code> to
include your
language as:
<codeblock>LANGUAGES = en ja fr
include $(basedir)/Makefile.i18n.common</codeblock>
<p>then type <code>make</code> in the directory. This should generate your
PHP (and
possibly some other) files as well as English and Japanese.</p>
</li>
</ol>
<p>Note:
If you see some misspelling or errors in the English
file, don't change it, but instead report it instead to the fink-i18n list, so
that the master English file is changed.
</p>
</section>
<section name="committing" >
<title>Committing the Changes</title>
<p>Now you need to send your changes to the main server. This process is a bit
different between the static and dynamic documents:</p>
<ul>
<li>
<em>Static: </em>
</li>
</ul>
</section>
</chapter>
<chapter filename="procedure" >
<title>Procedure for Updating Documents</title>
<shorttitle>Update Procedure.</shorttitle>
<preface>
<p>In order that things go smoothly, the following procedure should be followed..
</p>
</preface>
<section name="english" >
<title>Update English Documentation</title>
<p>Since the English documentation is the baseline, it must be updated first.
Such an update may come from a member of the i18n team (e.g. the English
Documentarians) or directly from the core developers.</p>
<p>There are a couple of classifications for documentation updates:</p>
<ol>
<li>
<em>Urgent (security, bugfixes, etc.):</em> The base English documentation
gets updated immediately, and translators update their individual documents and get
them online as soon as possible.</li>
<li>
<em>Not urgent:</em> In this case, the basic English documentation is
updated, but not put online immediately. All translators do their work and get their
version online within a day or two, then all versions get put online at the same
time.</li>
</ol>
</section>
<section name="call-to-translate" >
<title>Call to Translate</title>
<p>Once the English files are done, a message will be posted to the fink-18n
list informing all translators of the fact. The message will contain the
following:</p>
<ul>
<li>A note in the subject line indicating that this is a request for
translation, e.g. "[translation]", or "[translation-urgent]" for
items where the English documentation is going online immediately.
</li>
<li>In addition, the filename of the base file should be included somewhere in
the message.</li>
<li>A full diff (e.g. <code>diff -Nru3 -r<em>last_revision</em> r<em>head</em>
</code>) to show the modifications in context.</li>
</ul>
<p>Note: since committing the XML file automatically produces a message
on fink-commits that meets all of these criteria, an easy thing to do is to
redirect such a message and re-title the subject.</p>
</section>
<section name="translate" >
<title>Translation</title>
<p>Now the actual work of translation proceeds. When all of the
documents for a language are done, the files should be committed,
and a message sent to fink-i18n saying that the translation for that
language is done.</p>
</section>
<section name="activation" >
<title>Activating the Changes</title>
<p>There are two options for activating changes:</p>
<ol>
<li>For urgent changes, immediately after a language gets done, its
changes get activated.</li>
<li>For non-urgent changes, the changes will be activated after all
languages are finished.
</li>
</ol>
</section>
</chapter>
<chapter filename="resources" >
<title>Additional Resources.</title>
<shorttitle>resources</shorttitle>
<section name="resources" >
<p>
Internationalization is a complicated subject. The resources provided below
can serve as a valuable second source of information. You are advised to read them
carefully if you wish to delve deeper into this subject.
</p>
<ol>
<li>
<link url="http://www.w3.org/TR/unicode-xml/"; >Unicode in XML and other
Markup Languages</link>
</li>
<li>
<link url="http://www.w3.org/International/tutorials/tutorial-char-enc.html";
>Tutorial: Character sets & encodings</link>
</li>
<li>
<link url="http://www.w3.org/International/"; >W3C Internationalization
Activity</link>
</li>
<li>
<link url="http://www.cl.cam.ac.uk/~mgk25/unicode.html"; >UTF-8 and Unicode
FAQ for Unix/Linux</link>
</li>
</ol>
</section>
</chapter>
</document>
-------------------------------------------------------
This SF.Net email is sponsored by: IBM Linux Tutorials
Free Linux tutorial presented by Daniel Robbins, President and CEO of
GenToo technologies. Learn everything from fundamentals to system
administration.http://ads.osdn.com/?ad_id=1470&alloc_id=3638&op=click
_______________________________________________
Fink-commits mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/fink-commits
