Move doc/nls.texi to gettext-runtime/doc/nls.texi.

1 files changed, 253 insertions, 0 deletions

diff --git a/gettext-runtime/doc/nls.texi b/gettext-runtime/doc/nls.texi
new file mode 100644
index 0000000..af6916c
--- /dev/null
+++ b/gettext-runtime/doc/nls.texi
@@ -0,0 +1,253 @@
+@node Translation Intro
+@chapter Notes on the Free Translation Project
+
+@set STATUS October 2002
+
+Free software is going international!  The Free Translation Project is
+a way to get maintainers of free software, translators, and users all
+together, so that will gradually become able to speak many languages.
+A few packages already provide translations for their messages.
+
+If you found this @file{ABOUT-NLS} file inside a distribution, you
+may assume that the distributed package does use GNU @code{gettext}
+internally, itself available at your nearest GNU archive site.  But you
+do @emph{not} need to install GNU @code{gettext} prior to configuring,
+installing or using this package with messages translated.
+
+Installers will find here some useful hints.  These notes also explain
+how users should proceed for getting the programs to use the available
+translations.  They tell how people wanting to contribute and work
+at translations should contact the appropriate team.
+
+When reporting bugs in the @file{intl/} directory or bugs which may
+be related to internationalization, you should tell about the version
+of @code{gettext} which is used.  The information can be found in
+the @file{intl/VERSION} file, in internationalized packages.
+
+@menu
+* Configuration advice::
+* INSTALL Matters::
+* Using This Package::
+* Translating Teams::
+* Available Packages::
+* Using gettext in own code::
+@end menu
+
+@node Configuration advice
+@section Quick configuration advice
+
+If you want to exploit the full power of internationalization, you
+should configure it using
+
+@example
+./configure --with-included-gettext
+@end example
+
+@noindent
+to force usage of internationalizing routines provided within this
+package, despite the existence of internationalizing capabilities in the
+operating system where this package is being installed.  So far, only
+the @code{gettext} implementation in the GNU C library version 2
+provides as many features (such as locale alias, message inheritance,
+automatic charset conversion or plural form handling)
+as the implementation here.  It is also not possible to offer this
+additional functionality on top of a @code{catgets} implementation.
+Future versions of GNU @code{gettext} will very likely convey even more
+functionality.  So it might be a good idea to change to GNU
+@code{gettext} as soon as possible.
+
+So you need @emph{not} provide this option if you are using GNU libc 2 or
+you have installed a recent copy of the GNU gettext package with the
+included @file{libintl}.
+
+
+@node INSTALL Matters
+@section INSTALL Matters
+
+Some packages are @dfn{localizable} when properly installed; the
+programs they contain can be made to speak your own native language.
+Most such packages use GNU @code{gettext}.  Other packages have their
+own ways to internationalization, predating GNU @code{gettext}.
+
+By default, this package will be installed to allow translation of
+messages.  It will automatically detect whether the system already
+provides the GNU @code{gettext} functions.  If not, the GNU
+@code{gettext} own library will be used.  This library is wholly
+contained within this package, usually in the @file{intl/} subdirectory,
+so prior installation of the GNU @code{gettext} package is @emph{not}
+required.  Installers may use special options at configuration time for
+changing the default behaviour.  The commands:
+
+@example
+./configure --with-included-gettext
+./configure --disable-nls
+@end example
+
+@noindent
+will respectively bypass any pre-existing @code{gettext} to use the
+internationalizing routines provided within this package, or else,
+@emph{totally} disable translation of messages.
+
+When you already have GNU @code{gettext} installed on your system and
+run configure without an option for your new package, @code{configure}
+will probably detect the previously built and installed @file{libintl.a}
+file and will decide to use this.  This might be not what is desirable.
+You should use the more recent version of the GNU @code{gettext}
+library.  I.e. if the file @file{intl/VERSION} shows that the library
+which comes with this package is more recent, you should use
+
+@example
+./configure --with-included-gettext
+@end example
+
+@noindent
+to prevent auto-detection.
+
+The configuration process will not test for the @code{catgets} function
+and therefore it will not be used.  The reason is that even an
+emulation of @code{gettext} on top of @code{catgets} could not provide
+all the extensions of the GNU @code{gettext} library.
+
+Internationalized packages have usually many @file{po/@var{ll}.po}
+files, where @var{ll} gives an @w{ISO 639} two-letter code
+identifying the language.  Unless translations have been forbidden
+at @code{configure} time by using the @samp{--disable-nls} switch,
+all available translations are installed together with the package.
+However, the environment variable @code{LINGUAS} may be set, prior
+to configuration, to limit the installed set.  @code{LINGUAS} should
+then contain a space separated list of two-letter codes, stating
+which languages are allowed.
+
+@node Using This Package
+@section Using This Package
+
+@c --
+@c FIXME: rewrite to document the aliases.
+@c --
+As a user, if your language has been installed for this package, you
+only have to set the @code{LANG} environment variable to the appropriate
+@samp{@var{ll}_@var{CC}} combination.  Here @samp{@var{ll}} is an
+@w{ISO 639} two-letter language code, and @samp{@var{CC}} is an
+@w{ISO 3166} two-letter country code.  For example, let's suppose that you
+speak German and live in Germany.  At the shell prompt, merely execute
+@w{@samp{setenv LANG de_DE}} (in @code{csh}),
+@w{@samp{export LANG; LANG=de_DE}} (in @code{sh}) or
+@w{@samp{export LANG=de_DE}} (in @code{bash}).  This can be done from your
+@file{.login} or @file{.profile} file, once and for all.
+
+You might think that the country code specification is redundant.  But in
+fact, some languages have dialects in different countries.  For example,
+@samp{de_AT} is used for Austria, and @samp{pt_BR} for Brazil.  The country
+code serves to distinguish the dialects.
+
+The locale naming convention of @samp{@var{ll}_@var{CC}}, with
+@samp{@var{ll}} denoting the language and @samp{@var{CC}} denoting the
+country, is the one use on systems based on GNU libc.  On other systems,
+some variations of this scheme are used, such as @samp{@var{ll}} or
+@samp{@var{ll}_@var{CC}.@var{encoding}}.  You can get the list of
+locales supported by your system for your country by running the command
+@samp{locale -a | grep '^@var{ll}'}.
+
+Not all programs have translations for all languages.  By default, an
+English message is shown in place of a nonexistent translation.  If you
+understand other languages, you can set up a priority list of languages.
+This is done through a different environment variable, called
+@code{LANGUAGE}.  GNU @code{gettext} gives preference to @code{LANGUAGE}
+over @code{LANG} for the purpose of message handling, but you still
+need to have @code{LANG} set to the primary language; this is required
+by other parts of the system libraries.
+For example, some Swedish users who would rather read translations in
+German than English for when Swedish is not available, set @code{LANGUAGE}
+to @samp{sv:de} while leaving @code{LANG} to @samp{sv_SE}.
+
+In the @code{LANGUAGE} environment variable, but not in the @code{LANG}
+environment variable, @samp{@var{ll}_@var{CC}} combinations can be
+abbreviated as @samp{@var{ll}} to denote the language's main dialect.
+For example, @samp{de} is equivalent to @samp{de_DE} (German as spoken in
+Germany), and @samp{pt} to @samp{pt_PT} (Portuguese as spoken in Portugal)
+in this context.
+
+@c An operating system might already offer message localization for many of
+@c its programs, while other programs have been
+@c installed locally with the full capabilities of GNU @code{gettext}.
+@c Just using @code{gettext} extended syntax for @code{LANG} would break
+@c proper localization of already available operating system programs.
+@c FIXME: The user doesn't care about design justifications. --bruno
+
+@node Translating Teams
+@section Translating Teams
+
+For the Free Translation Project to be a success, we need interested
+people who like their own language and write it well, and who are also
+able to synergize with other translators speaking the same language.
+Each translation team has its own mailing list.  The up-to-date list
+of teams can be found at the Free Translation Project's homepage,
+@file{http://www.iro.umontreal.ca/contrib/po/HTML/}, in the
+"National teams" area.
+
+If you'd like to volunteer to @emph{work} at translating messages, you
+should become a member of the translating team for your own language.
+The subscribing address is @emph{not} the same as the list itself, it
+has @samp{-request} appended.  For example, speakers of Swedish can send
+a message to @w{@file{sv-request@@li.org}}, having this message body:
+
+@example
+subscribe
+@end example
+
+Keep in mind that team members are expected to participate
+@emph{actively} in translations, or at solving translational
+difficulties, rather than merely lurking around.  If your team does not
+exist yet and you want to start one, or if you are unsure about what to
+do or how to get started, please write to
+@w{@file{translation@@iro.umontreal.ca}} to reach the
+coordinator for all translator teams.
+
+The English team is special.  It works at improving and uniformizing
+the terminology in use.  Proven linguistic skill are praised
+more than programming skill, here.
+
+@node Available Packages
+@section Available Packages
+
+Languages are not equally supported in all packages.  The following
+matrix shows the current state of internationalization, as of
+@value{STATUS}.  The matrix shows, in regard of each package, for which
+languages PO files have been submitted to translation coordination,
+with a translation percentage of at least 50%.
+
+@include matrix.texi
+
+Some counters in the preceding matrix are higher than the number of visible
+blocks let us expect.  This is because a few extra PO files are used for
+implementing regional variants of languages, or language dialects.
+
+For a PO file in the matrix above to be effective, the package to which
+it applies should also have been internationalized and distributed as
+such by its maintainer.  There might be an observable lag between the
+mere existence a PO file and its wide availability in a distribution.
+
+If @value{STATUS} seems to be old, you may fetch a more recent copy
+of this @file{ABOUT-NLS} file on most GNU archive sites.  The most
+up-to-date matrix with full percentage details can be found at
+@file{http://www.iro.umontreal.ca/contrib/po/HTML/matrix.html}.
+
+
+@node Using gettext in own code
+@section Using @code{gettext} in new packages
+
+If you are writing a freely available program and want to internationalize
+it you are welcome to use GNU @file{gettext} in your package.  Of course
+you have to respect the GNU Library General Public License which covers
+the use of the GNU @file{gettext} library.  This means in particular that
+even non-free programs can use @code{libintl} as a shared library, whereas
+only free software can use @code{libintl} as a static library or use
+modified versions of @code{libintl}.
+
+Once the sources are changed appropriately and the setup can handle to
+use of @code{gettext} the only thing missing are the translations.  The
+Free Translation Project is also available for packages which are not
+developed inside the GNU project.  Therefore the information given above
+applies also for every other Free Software Project.  Contact
+@w{@file{translation@@iro.umontreal.ca}} to make the @file{.pot} files
+available to the translation teams.