Invenio NATIVE LANGUAGE SUPPORT
===============================

About
=====

This document describes the Native Language Support (NLS) in Invenio.

Contents
========

1. Native Language Support information for administrators
2. Native Language Support information for translators
3. Native Language Support information for programmers
A. Introducing a new language
B. Integrating translation contributions

1. Native Language Support information for administrators
=========================================================

Invenio is currently available in the following languages:

   af = Afrikaans
   bg = Bulgarian
   ca = Catalan
   cs = Czech
   de = German
   el = Greek
   en = English
   es = Spanish
   fr = French
   gl = Galician
   hr = Croatian
   hu = Hungarian
   it = Italian
   ja = Japanese
   ka = Georgian
   no = Norwegian (Bokmål)
   pl = Polish
   pt = Portuguese
   ro = Romanian
   ru = Russian
   rw = Kinyarwanda
   sk = Slovak
   sv = Swedish
   uk = Ukrainian
   zh_CN = Chinese (China)
   zh_TW = Chinese (Taiwan)

If you are installing Invenio and you want to enable/disable some
languages, please just follow the standard installation procedure as
described in the INSTALL file.  The default language of the
installation as well as the list of all user-seen languages can be
selected in the general invenio.conf file, see variables CFG_SITE_LANG
and CFG_SITE_LANGS.

(Please note that some runtime Invenio daemons -- such as webcoll,
responsible for updating the collection cache, running every hour or
so -- may work twice as long when twice as many user-seen languages
are selected, because it creates collection cache page elements for
every user-seen language.  Therefore, if you have defined thousands of
collections and if you find the webcoll speed to be slow in your
setup, you may want to try to limit the list of selected languages.)

2. Native Language Support information for translators
======================================================

We are using Transifex for handling translations. Please see the
Transifex's Getting Started guide:

  http://docs.transifex.com/getting-started/translators/

The PO catalog files for Invenio 1.0 with messages to be translated
are located in:

  https://www.transifex.com/inveniosoftware/invenio/invenio-maint-10-messages/

3. Native Language Support information for programmers
======================================================

Invenio uses standard GNU gettext I18N and L12N philosophy.

In Python programs, all output strings should be made translatable via
the _() convention:

   from messages import gettext_set_language
   [...]
   def square(x, ln=CFG_SITE_LANG):
       _ = gettext_set_language(ln)
       print _("Hello there!")
       print _("The square of %s is %s.") % (x, x*x)

In webdoc source files, the convention is _()_:

   _(Search Help)_

Here are some tips for writing easily translatable output messages:

  - Do not cut big phrases into several pieces, the meaning may be
    harder to grasp and to render properly in another language.  Leave
    them in the context.  Do not try to economize and reuse
    standalone-translated words as parts of bigger sentences.  The
    translation could differ due to gender, for example.  Rather
    define two sentences instead:

       not: _("This %s is not available.") % x,
            where x is either _("basket") or _("alert")

       but: _("This basket is not available.") and
            _("This alert is not available.")

  - If you print some value in a translatable phrase, you can use an
    unnamed %i or %s string replacement placeholders:

       yes: _("There are %i baskets.") % nb_baskets

    But, as soon as you are printing more than one value, you should
    use named string placeholders because in some languages the parts
    of the sentence may be reversed when translated:

       not: _("There are %i baskets shared by %i groups.") % \
               (nb_baskets, nb_groups)
       but: _("There are %(x_nb_baskets)s baskets shared by %(x_nb_groups)s groups.") % \
               {'x_nb_baskets': nb_baskets, 'x_nb_groups': nb_groups,}

    Please use the `x_' prefix for the named placeholder variables to
    ease the localization task of the translator.

  - Do not mix HTML presentation inside phrases. If you want to
    reserve space for HTML markup, please use generic replacement
    placeholders as prologue and epilogue:

       not: _("This is <b>cold</b>.")
       but: _("This is %(x_fmt_open)scold%(x_fmt_close)s.")

    Ditto for links:

       not: _("This is <a href="%s">homepage</a>.")
       not: _("This is %(x_url_open)shomepage%(x_url_close)s.")

  - Do not leave unnecessary things in short commonly used
    translatable expressions, such as extraneous spaces or colons
    before or after them.  Rather put them in the business logic:

       not: _(" subject")
       but: " " + _("subject")

       not: _("Record %i:")
       but: _("Record") + "%i:" % recID

    On the other hand, in long sentences when the trailing punctuation
    has its meaning as an integral part of the label to be shown on
    the interface, you should leave them:

       not: _("Nearest terms in any collection are")
       but: _("Nearest terms in any collection are:")

  - Last but not least: the best is to follow the style of existing
    messages as a model, so that the translators are presented with a
    homogeneous and consistently presented output phrase set.

Appendix A. Introducing a new language
======================================

If you would like to introduce a new language for the first time,
then please contact us so that we can add it on Transifex.

In addition to the phrases hosted there, please send us the
following translations by email:

   - demo server name, from invenio.conf:

        Atlantis Institute of Fictive Science

   - demo collection names, from democfgdata.sql:

        Preprints
        Books
        Theses
        Reports
        Articles
        Pictures
        CERN Divisions
        CERN Experiments
        Theoretical Physics (TH)
        Experimental Physics (EP)
        Articles & Preprints
        Books & Reports
        Multimedia & Arts
        Poetry

   - demo right-hand-side portalbox, from democfgdata.sql:

        ABOUT THIS SITE
        Welcome to the demo site of the Invenio, a free document server
        software coming from CERN. Please feel free to explore all the
        features of this demo site to the full.
        SEE ALSO

The development team will then edit various files (po/LINGUAS, config
files, sql files, plenty of Makefile files, etc) as needed.

The last phase of the initial introduction of the new language would
be to translate some short static HTML pages such as:

   - modules/webhelp/web/help-central.webdoc

Thanks for helping us to internationalize Invenio.

Appendix B. Integrating translation contributions
=================================================

The contributed translations are updated by the Invenio maintainers
by using the usual Transifex client methods. (E.g. "tx pull -a".)

- end of file -