GSA INTERNATIONALIZATION HOWTO
##############################

Requirements
============
In addition to the usual GSA requirements, the following are needed as well:
- msgmerge (part of the GNU gettext tools)
- Python (scripts were tested with version 2.7.3)
- polib (Python gettext manipulation library)

If you are using a .po file editor, make sure it supports "msgctxt" and
 plural forms correctly. (Some older editors may not.)


General notes
=============
- GSA uses UTF-8 text encoding, so you should use this for your translations
 as well.
- Most GSA pages now use gettext for translations while the custom XML-based
 format is no longer used. (See section "Migrating old XML translations" on
 how to migrate translations using this format.)
- Help pages are translated separately. See "Translating help pages" for more.
- Charts are currently not translated.


Updating existing translations
==============================
To update existing translations using the gettext format follow these steps.
 For old XML-based translations, see "Migrating old XML translations".

1 - Creating a new template (.pot) file
---------------------------------------
To create a new template file run

  make gettext-pot-files

which will generate the file "gsad_xsl.pot" in the "src/po" subdirectory of
 your build directory.
You can then use this as a template for your new translation.

Alternatively you can run the script directly:

  python "${SRC_DIR}/tools/xsl2pot" "${SRC_DIR}/src/html/classic" "${OUT_FILE}"

with ${SRC_DIR} being the GSA source directory and ${OUT_FILE} being the path
 to your desired output file.


2 - Merge the template and existing translations
------------------------------------------------
To merge the template run

  make gettext-po-files

This will generate "gsad_xsl-XX-merged.po" files in the "src/po" subdirectory
 of your build directory, with "XX" being ISO 639 language codes.

3 - Copying the merged .po
--------------------------
The next step is to copy the file for your language to "src/po" in the
 source directory, removing the part "-merged" from the file name.

As this means overwrites the old source .po file, you should verify the new
 file is correct and/or backup the old file first.

4 - Update the translations
---------------------------
Finally you can can update the actual translations in the .po file.
To apply the changes, build, install and restart GSA.

(Technically you can update the merged .po before copying and installing it,
 but doing it last allows testing the translations in progress)



Creating new translations
=========================
1 - Creating the template (.pot) file
-------------------------------------
The first step to a new translation is generating a new template (.pot) file.
To do so, follow the first step under "Updating existing translations".

The destination file of the make target is "gsad_xsl.pot" in the "src/po"
 subdirectory of your GSA source directory.


2 - Preparing the .po file
--------------------------
Next you have to use the generated file as a template for your new translation.

Once you are finished or want to install the in-progress translation for
 testing, copy it to "src/po/gsad_xsl-XX.po" in your source directory with "XX"
 being the ISO 639-1 code of your target language.
If no ISO 639-1 code exists, use the ISO 639-2 three-letter code instead.


3 - Setting up the installation
-------------------------------
In the file "CMakeLists.txt" in the "src/po" add a line

  MAKE_TRANSLATION (XX)

near the other MAKE_TRANSLATION (...) lines, with "XX" again being the ISO
 language code.

Also add your language to the dependencies of the targets "gettext-mo-files"
 and "gettext-po-files", again replacing XX with the language code:

  add_custom_target (gettext-mo-files
                     [...]
                     DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/XX/gsad_xsl.mo)

  add_custom_target (gettext-po-files
                     DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/gsad_xsl.pot
                     [...]
                     DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/gsad_xsl-XX-merged.po)


Migrating old XML translations
==============================
Translations using the old XML-based format can be partially migrated by
 converting the old XML file to PO.

1 - Convert the XML to PO
-------------------------
First run the XML to PO conversion script:

  python "${SRC_DIR}/tools/xml2po" "${XML_FILE}" "${PO_FILE}"

with ${SRC_DIR} being the GSA source directory, ${XML_FILE} the XML translation
 file and ${PO_FILE} the destination po file.
The destination file should be "gsad_xsl-XX.po" in the "src/po" subdirectory of
 your GSA source directory, replacing "XX" with the ISO 639-1 or 639-2 code
 of your target language.


2 - Set up the build file
-------------------------
Next you should set up the build file for your newly migrated language as
 described in point 3 of the section "Creating new translations".


3 - Create and merge the .pot file
----------------------------------
Next create a new .pot file and merge it with the .po file you just generated
 as described in the section "Updating existing translations".

Many of the translations will be marked as unfinished / fuzzy as many context
 names were changed as part of switching to the gettext format. You should be
 able to quickly change them with a suitable .po file editor.
Beware that there are also some cases where the actual message text has changed
 as well, mostly to make messages less fragmented.

After updating the messages, proceed as you would with a regular update of the
 translation.
Since the migration leaves many unused contexts and text fragments it may be
 a good idea to remove the unused messages to reduce the file size once the
 update is complete.


Message Contexts
================
The messages in GSA all use the msgctxt to either point to the resource type
 they are used (which can be important to determine the grammatical gender
 of adjective for example) for or to disambiguate in another way how they are
 used (for example if a word like "login" used as a noun or a verb).

Resource-specific messages
--------------------------
Most messages that are specific to a certain resource type will use the
 singular type name (e.g. "Port List") as the context.

In cases where there is ambiguity regarding the number of resources referred
 to, the plural (e.g. "Port Lists") will be used if the message is used
 in a context where it can be referring to multiple resources.
For examples if "None" refers to the selection of a single resource, the
 singular is used, but when it refers to a list of resources, the plural is
 used as the context.

Nested contexts
---------------
In some cases contexts can contain subcontexts like groups or values of
 properties of resource types, which are appended to the parent context
 after a vertical line symbol.

For example "Total" having the context "Task|Reports" means that the message
 is referring to the total number of Reports of a Task.
Or "Task|Hosts Ordering" means that a string is a possible value for the
 "Hosts Ordering" property of a Task.

Generic contexts
----------------

Actions
  This is a context for the "Actions" column header in resource lists.

Action Verb
  Messages in this context are used for labeling UI elements performing an
  action rather than referring to the concept of the action itself.
  For example "Login" in this context is used on a button for actually logging
  in while in another context it may be used as a noun, for example as
  a short version of "Login name" or "Login attempt".
  Most of these messages are verbs in the grammatical sense, but in some cases
  the actual verb can be implied, for example "To Trashcan" is short for
  "Move to Trashcan".

Binary Choice
  This refers to a simple choice with two options (yes/no, true/false) and is
  mainly used to clarify that "no" is used this way, not in the sense of
  "zero" as in "no items were found".

Date
  This means the string is referring to a calendar date. For example

Login Data
  Generic login data related messages like "Username" and "Password" not
  specific to LSC Credential objects.

Login Message
  Messages returned by the GSA login page.

Meta Property
  This context is used for messages that describe properties, for example if
  a property is optional or immutable.

Pagination
  These are messages used in the pagination, e.g. on buttons for the first
  and last page or in text like "Results 1 to 10".

Property
  These messages are either frequently reused nouns that name something
  describing a resource (for example "Name" or "Comment").

Time
  This means the message is referring to a time span or a point in time.
  For example "second" in this context means the time unit, not an item after
  a first one.

Value
  A common generic property value like "N/A"


Translating help pages
======================
Translations for the help pages are contained in a file called "help_<lc>.xsl",
where <lc> is the two-letter language code the translation is for.

For the stylesheet to work properly, it must include the default "help.xsl"
at the beginning. 

Next should be the named templates, which must use different names than the
included default stylesheets. This is to avoid conflicts which would not only
affect the template, but cause all of the XSL transformation to fail.

For consistency you should use the name of their default stylesheet equivalent
suffixed with an underscore and the language code.
For example "availability" becomes "availability_de" if the language code is
"de".

After this the "Page not found" template should be placed, followed by the
individual page templates.

The new help file should also be UTF-8 encoded and has to be installed in the
directory ${GSA_DATA_DIR}/classic.
