gettext-runtime/doc/nls.texi

   1 @node Translation Intro
   2 @chapter Notes on the Free Translation Project
   3
   4 @set STATUS Jun 2014
   5
   6 Free software is going international!  The Free Translation Project is
   7 a way to get maintainers of free software, translators, and users all
   8 together, so that free software will gradually become able to speak many
   9 languages.  A few packages already provide translations for their messages.
  10
  11 If you found this @file{ABOUT-NLS} file inside a distribution, you
  12 may assume that the distributed package does use GNU @code{gettext}
  13 internally, itself available at your nearest GNU archive site.  But you
  14 do @emph{not} need to install GNU @code{gettext} prior to configuring,
  15 installing or using this package with messages translated.
  16
  17 Installers will find here some useful hints.  These notes also explain
  18 how users should proceed for getting the programs to use the available
  19 translations.  They tell how people wanting to contribute and work
  20 on translations can contact the appropriate team.
  21
  22 @menu
  23 * INSTALL Matters::
  24 * Using This Package::
  25 * Translating Teams::
  26 * Available Packages::
  27 * Using gettext in own code::
  28 @end menu
  29
  30
  31 @node INSTALL Matters
  32 @section INSTALL Matters
  33
  34 Some packages are @dfn{localizable} when properly installed; the
  35 programs they contain can be made to speak your own native language.
  36 Most such packages use GNU @code{gettext}.  Other packages have their
  37 own ways to internationalization, predating GNU @code{gettext}.
  38
  39 By default, this package will be installed to allow translation of
  40 messages.  It will automatically detect whether the system already
  41 provides the GNU @code{gettext} functions.  Installers may use special
  42 options at configuration time for changing the default behaviour.  The
  43 command:
  44
  45 @example
  46 ./configure --disable-nls
  47 @end example
  48
  49 @noindent
  50 will @emph{totally} disable translation of messages.
  51
  52 When you already have GNU @code{gettext} installed on your system and
  53 run configure without an option for your new package, @code{configure}
  54 will probably detect the previously built and installed @file{libintl}
  55 library and will decide to use it.  If not, you may have to to use the
  56 @samp{--with-libintl-prefix} option to tell @code{configure} where to
  57 look for it.
  58
  59 Internationalized packages usually have many @file{po/@var{ll}.po}
  60 files, where @var{ll} gives an @w{ISO 639} two-letter code
  61 identifying the language.  Unless translations have been forbidden
  62 at @code{configure} time by using the @samp{--disable-nls} switch,
  63 all available translations are installed together with the package.
  64 However, the environment variable @code{LINGUAS} may be set, prior
  65 to configuration, to limit the installed set.  @code{LINGUAS} should
  66 then contain a space separated list of two-letter codes, stating
  67 which languages are allowed.
  68
  69 @node Using This Package
  70 @section Using This Package
  71
  72 @c Note: We don't document the locale aliases, because they are less and less
  73 @c used - locale.alias contains not a single UTF-8 locale and still lists
  74 @c ISO-8859-1 for countries which have long adopted the Euro and switched to
  75 @c ISO-8859-15.
  76 @c
  77 As a user, if your language has been installed for this package, you
  78 only have to set the @code{LANG} environment variable to the appropriate
  79 @samp{@var{ll}_@var{CC}} combination.  If you happen to have the @code{LC_ALL}
  80 or some other @code{LC_xxx} environment variables set, you should unset them
  81 before setting @code{LANG}, otherwise the setting of @code{LANG} will not
  82 have the desired effect.  Here @samp{@var{ll}} is an
  83 @w{ISO 639} two-letter language code, and @samp{@var{CC}} is an
  84 @w{ISO 3166} two-letter country code.  For example, let's suppose that you
  85 speak German and live in Germany.  At the shell prompt, merely execute
  86 @w{@samp{setenv LANG de_DE}} (in @code{csh}),
  87 @w{@samp{export LANG; LANG=de_DE}} (in @code{sh}) or
  88 @w{@samp{export LANG=de_DE}} (in @code{bash}).  This can be done from your
  89 @file{.login} or @file{.profile} file, once and for all.
  90
  91 You might think that the country code specification is redundant.  But in
  92 fact, some languages have dialects in different countries.  For example,
  93 @samp{de_AT} is used for Austria, and @samp{pt_BR} for Brazil.  The country
  94 code serves to distinguish the dialects.
  95
  96 The locale naming convention of @samp{@var{ll}_@var{CC}}, with
  97 @samp{@var{ll}} denoting the language and @samp{@var{CC}} denoting the
  98 country, is the one use on systems based on GNU libc.  On other systems,
  99 some variations of this scheme are used, such as @samp{@var{ll}} or
 100 @samp{@var{ll}_@var{CC}.@var{encoding}}.  You can get the list of
 101 locales supported by your system for your language by running the command
 102 @samp{locale -a | grep '^@var{ll}'}.
 103
 104 Not all programs have translations for all languages.  By default, an
 105 English message is shown in place of a nonexistent translation.  If you
 106 understand other languages, you can set up a priority list of languages.
 107 This is done through a different environment variable, called
 108 @code{LANGUAGE}.  GNU @code{gettext} gives preference to @code{LANGUAGE}
 109 over @code{LANG} for the purpose of message handling, but you still
 110 need to have @code{LANG} set to the primary language; this is required
 111 by other parts of the system libraries.
 112 For example, some Swedish users who would rather read translations in
 113 German than English for when Swedish is not available, set @code{LANGUAGE}
 114 to @samp{sv:de} while leaving @code{LANG} to @samp{sv_SE}.
 115
 116 Special advice for Norwegian users: The language code for Norwegian
 117 bokm@ringaccent{a}l changed from @samp{no} to @samp{nb} recently (in 2003).
 118 During the transition period, while some message catalogs for this language
 119 are installed under @samp{nb} and some older ones under @samp{no}, it's
 120 recommended for Norwegian users to set @code{LANGUAGE} to @samp{nb:no} so that
 121 both newer and older translations are used.
 122
 123 In the @code{LANGUAGE} environment variable, but not in the @code{LANG}
 124 environment variable, @samp{@var{ll}_@var{CC}} combinations can be
 125 abbreviated as @samp{@var{ll}} to denote the language's main dialect.
 126 For example, @samp{de} is equivalent to @samp{de_DE} (German as spoken in
 127 Germany), and @samp{pt} to @samp{pt_PT} (Portuguese as spoken in Portugal)
 128 in this context.
 129
 130 @c An operating system might already offer message localization for many of
 131 @c its programs, while other programs have been
 132 @c installed locally with the full capabilities of GNU @code{gettext}.
 133 @c Just using @code{gettext} extended syntax for @code{LANG} would break
 134 @c proper localization of already available operating system programs.
 135 @c FIXME: The user doesn't care about design justifications. --bruno
 136
 137 @node Translating Teams
 138 @section Translating Teams
 139
 140 For the Free Translation Project to be a success, we need interested
 141 people who like their own language and write it well, and who are also
 142 able to synergize with other translators speaking the same language.
 143 Each translation team has its own mailing list.  The up-to-date list
 144 of teams can be found at the Free Translation Project's homepage,
 145 @file{http://translationproject.org/}, in the "Teams" area.
 146
 147 If you'd like to volunteer to @emph{work} at translating messages, you
 148 should become a member of the translating team for your own language.
 149 The subscribing address is @emph{not} the same as the list itself, it
 150 has @samp{-request} appended.  For example, speakers of Swedish can send
 151 a message to @w{@file{sv-request@@li.org}}, having this message body:
 152
 153 @example
 154 subscribe
 155 @end example
 156
 157 Keep in mind that team members are expected to participate
 158 @emph{actively} in translations, or at solving translational
 159 difficulties, rather than merely lurking around.  If your team does not
 160 exist yet and you want to start one, or if you are unsure about what to
 161 do or how to get started, please write to
 162 @w{@file{coordinator@@translationproject.org}} to reach the
 163 coordinator for all translator teams.
 164
 165 The English team is special.  It works at improving and uniformizing
 166 the terminology in use.  Proven linguistic skills are praised
 167 more than programming skills, here.
 168
 169 @node Available Packages
 170 @section Available Packages
 171
 172 Languages are not equally supported in all packages.  The following
 173 matrix shows the current state of internationalization, as of
 174 @value{STATUS}.  The matrix shows, in regard of each package, for which
 175 languages PO files have been submitted to translation coordination,
 176 with a translation percentage of at least 50%.
 177
 178 @include matrix.texi
 179
 180 Some counters in the preceding matrix are higher than the number of visible
 181 blocks let us expect.  This is because a few extra PO files are used for
 182 implementing regional variants of languages, or language dialects.
 183
 184 For a PO file in the matrix above to be effective, the package to which
 185 it applies should also have been internationalized and distributed as
 186 such by its maintainer.  There might be an observable lag between the
 187 mere existence a PO file and its wide availability in a distribution.
 188
 189 If @value{STATUS} seems to be old, you may fetch a more recent copy
 190 of this @file{ABOUT-NLS} file on most GNU archive sites.  The most
 191 up-to-date matrix with full percentage details can be found at
 192 @file{http://translationproject.org/extra/matrix.html}.
 193
 194
 195 @node Using gettext in own code
 196 @section Using @code{gettext} in new packages
 197
 198 If you are writing a freely available program and want to internationalize
 199 it you are welcome to use GNU @file{gettext} in your package.  Of course
 200 you have to respect the GNU Lesser General Public License which covers
 201 the use of the GNU @file{gettext} library.  This means in particular that
 202 even non-free programs can use @code{libintl} as a shared library, whereas
 203 only free software can use @code{libintl} as a static library or use
 204 modified versions of @code{libintl}.
 205
 206 Once the sources are changed appropriately and the setup can handle the
 207 use of @code{gettext} the only thing missing are the translations.  The
 208 Free Translation Project is also available for packages which are not
 209 developed inside the GNU project.  Therefore the information given above
 210 applies also for every other Free Software Project.  Contact
 211 @w{@file{coordinator@@translationproject.org}} to make the @file{.pot} files
 212 available to the translation teams.