trans-coord/gnun/prep/gnun gnun.texi ChangeLog

[Kaloian Doganov]

CVSROOT:        /sources/trans-coord
Module name:    trans-coord
Changes by:     Kaloian Doganov <kaloian>       08/02/14 09:15:54

Modified files:
        gnun/prep/gnun : gnun.texi ChangeLog 

Log message:
        * gnun.texi (Concepts): More explanations and a diagram for the
        "big picture".  Influenced by the relevant section in
        gettext.texi.
        (Advantages): Replace "immigrants" with "speakers".

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/prep/gnun/gnun.texi?cvsroot=trans-coord&r1=1.6&r2=1.7
http://cvs.savannah.gnu.org/viewcvs/trans-coord/gnun/prep/gnun/ChangeLog?cvsroot=trans-coord&r1=1.46&r2=1.47

Patches:
Index: gnun.texi
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/prep/gnun/gnun.texi,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- gnun.texi   10 Feb 2008 11:49:55 -0000      1.6
+++ gnun.texi   14 Feb 2008 09:15:53 -0000      1.7
@@ -4,7 +4,7 @@
 @settitle GNUnited Nations Manual
 @c FIXME: Would be nice to have it in the format `%:b %:d, %:y', but
 @c in English.
address@hidden lastupdate 10.02.2008
address@hidden lastupdate 14.02.2008
 @c %**end of header
 
 @c Please do not use features of Texinfo >> 4.8, which is the version
@@ -134,19 +134,117 @@
 @node Concepts
 @section What @acronym{GNU}nited Nations is and Should be
 
-The basic goal behind @acronym{GNUN} is to transform the original
-English articles to ``PO templates'', suitable for manipulation with
-the various `gettext' utilities.  @xref{Top, , Introduction, gettext,
-GNU gettext tools}, for a basic overview.  The translations are kept
-as PO files, based on the PO templates (`PO' for short), and being
-transformed in HTML format with another collection of tools, Po4a
-(@uref{http://po4a.alioth.debian.org}).
-
-If the original article changes, the POT is automatically rebuilt, as
-well as all translations that already have a PO file installed.  Thus,
-if something changes in the English article, the relevant element in
-the translations will be substituted with the English text, until the
-translation teams update them.
+The basic concept behind @acronym{GNUN} is that localization of HTML
+articles is similar to localization of computer programs.  In
+articles, like in programs, not every string is considered
+translatable, so translatable strings must be identified first, and
+then collected in a file (called ``PO template'') for translation.
+Articles, like programs, tend to change in time, but not every change
+in the sources calls for a translation update.  Sometimes the change
+does not affect the translatable strings, but sometimes it does.  So,
+translators must have means to identify those changes and apply the
+appropriate updates to the translation.
+
address@hidden @code{gettext} package already provides the needed
+infrastructure for maintaining translations using PO files.
address@hidden, , Introduction, gettext, GNU gettext tools}, for a basic
+overview.  @acronym{GNU}nited Nations fills the gaps to apply this
+infrastructure to articles in @url{http://gnu.org} web
address@hidden process of converting HTML to PO and the other way
+around is performed using po4a (po for anything), see
address@hidden://po4a.alioth.debian.org}.}
+
+The following diagram summarizes the relation between the files
+handled by @acronym{GNUN}.  It is followed by somewhat detailed
+explanations, which you should read while keeping an eye on the
+diagram.  Having a clear understanding of these interrelations will
+suerly help translators and web maintainers.
+
address@hidden
address@hidden
+.---<--- * Original ARTICLE.html
+|
+|   .---> ARTICLE.pot ---> * ARTICLE.LANG.po --->---.
+`---+                                               |
+    `--->---.   .------<----------------------------'
+            |   |
+            |   `---.
+            |       +---> Translated ARTICLE.LANG.html
+            `-------'
address@hidden group
address@hidden example
+
+The indication @samp{*} appears in two places in this picture, and
+means that the corresponding file is intended to be edited by humans.
+The author or web maintainer edits the original
address@hidden@var{article}.html}, and translators edit
address@hidden@address@hidden  All other files are regenerated
+by @acronym{GNUN} and any manual changes on them will be lost on the
+next run.
+
+Arrows denote dependency relation between files, where a change in one
+file will affect the other.  Those automatic changes will be applied
+by running @samp{make -C prep/gnun}.  This is the primary way to
+invoke @acronym{GNUN}, since it is implemented as a set of recipes for
address@hidden @code{make}.
+
+First, @acronym{GNUN} extracts all translatable strings from the
+original English article @address@hidden into
address@hidden@var{article}.pot}.  The resulted file is suitable for
+manipulation with the various @acronym{GNU} @samp{gettext} utilities.
+It contains all original article strings and all translations are set
+to empty.  The letter @code{t} in @file{.pot} marks this as a Template
+PO file, not yet oriented towards any particular language.
+
+The first time through, there is no @address@hidden@var{lang}.po}
+yet, so translator must manually copy @address@hidden to
address@hidden@address@hidden, where @var{lang} represents the
+target language.  See FIXME:``Introducing new translation language for
+an article'' for details.
+
+Then comes the initial translation of messages in
address@hidden@address@hidden  Translation in itself is a whole
+matter, whose complexity far overwhelms the level of this manual.
+Nevertheless, a few hints are given in some other chapter of this
+manual (FIXME:Translators (but only if we would like to include some
+practical advices to candidate translators on how to join a gnu.org
+translating team)).  You will also find there indications about how to
+contact translating teams, or becoming part of them, for sharing your
+translating concerns with others who target the same native language.
+
+You may use any compatible PO editor to add translated messages into
+the PO file.  @xref{Editing, , Editing, gettext, GNU gettext tools},
+for more information.
+
+When the PO file actually exists (hopefully populated with initial
+translations), @acronym{GNUN} generates
address@hidden@address@hidden file.  It takes it's structure
+from the original @address@hidden, but all translatable
+strings are replaced with their translations specified in
address@hidden@address@hidden
+
+Original articles sometimes change.  A new paragraph is being added or
+a tiny change in the wording is introduced.  Also, some articles are
+dynamic in nature, like ones containing news entries or a list of
+other articles.  If the original article changes, @acronym{GNUN} will
+automatically rebuild @address@hidden, and will merge the
+changes to @address@hidden@var{lang}.po}.  Any outdated
+translations will be marked as fuzzy, any new strings will be added
+with empty translations, waiting to be translated.  In the same run
address@hidden@address@hidden will be rebuilt so the relevant
+strings in the translation will be substituted with the original
+English text, until the translation teams update them in
address@hidden@address@hidden
+
+Those changes in the original article that do not affect the
+translatable strings will not lead to changes in
address@hidden@address@hidden  Thus, no actions from translators
+will be needed.  @address@hidden@var{lang}.html} will be
+automatically regenerated to reflect the changes.
+
+FIXME: The following paragraphs should go to a separate section that
+explains those details like exact paths in www, diagram with the basic
+directory layout, additional files like .translinks, etc.
 
 The POT for every article under @acronym{GNUN}'s control is kept in
 the `www' repository under a special directory @file{po/}, which is a
@@ -197,9 +295,9 @@
 relevant to a single country or even a particular city.  Such a notice
 will propagate to all pages, and translators may choose whether to
 translate it or not.  For example, the Urdu translation team may
-conclude that there are only a few Urdu immigrants in Massachusetts,
-to participate in an event that will happen in Boston, so translating
-the ``urgent'' notice may not be very ``urgent'' for Urdu.  When the
+conclude that there are only a few Urdu speakers in Massachusetts, to
+participate in an event that will happen in Boston, so translating the
+``urgent'' notice may not be very ``urgent'' for Urdu.  When the
 notice is removed, often in a week or two, it will disappear without
 translators' intervention, whether they translated it or not.
 

Index: ChangeLog
===================================================================
RCS file: /sources/trans-coord/trans-coord/gnun/prep/gnun/ChangeLog,v
retrieving revision 1.46
retrieving revision 1.47
diff -u -b -r1.46 -r1.47
--- ChangeLog   13 Feb 2008 07:16:10 -0000      1.46
+++ ChangeLog   14 Feb 2008 09:15:53 -0000      1.47
@@ -1,3 +1,10 @@
+2008-02-14  Kaloian Doganov  <address@hidden>
+
+       * gnun.texi (Concepts): More explanations and a diagram for the
+       "big picture".  Influenced by the relevant section in
+       gettext.texi.
+       (Advantages): Replace "immigrants" with "speakers".
+
 2008-02-13  Kaloian Doganov  <address@hidden>
 
        * README: Mention "W3C XHMTL 1.0 DTDs" as an upstream package name