Evergreen DokuWiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Evergreen translations ======
Evergreen translations can be found and managed in [[https://translations.launchpad.net/evergreen/|Launchpad]]. Evergreen is translated with Open permissions - it means anyone can submit translations directly to the project in Launchpad ([[ https://login.launchpad.net/0Llx9dRODKgBKpo5/+decide | registration]] is required to edit the translations).

===== Understanding the translations workflow =====




If new features of Evergreen and code is written, some parts of the code contains text strings that need to be translated. To manage translations, POT and PO files are used.

==== POT files ====

//POT// stands for Portable Object Template i.e., the file that you get when you extract texts from the application.
==== PO files ====

//PO// files are the files containing the translations. Each language have its own PO file, e.g., Czech translation  in Evergreen has //cs-CZ.po// file, Spanish has //es-ES.po// file etc.

Usually an application is used to manage translations in PO files, e.g., desktop tool [[ https://poedit.net/| Poedit]] or online tools like [[ https://translations.launchpad.net/evergreen |Launchpad]] and [[https://poeditor.com/|Poeditor]], both used for Evergreen  translations.

The PO file consists of pairs of the text extracted from the code:
  - //ID//,  indicated as //msgid// (message id) 
  - The text of the translation, indicated as //msgstr// (message string). 

Useful comments (like developers note to translators or location of the text string in the file system) can be added to each pair.

**Example of the //id// and //string// pair with the comments (in the Czech PO file):**

<code>
#: ../../Open-ILS/src/templates/opac/parts/config.tt2:1
msgid "All Libraries"
msgstr "Všechny knihovny"

#. (bib_lib_name)
#: ../../Open-ILS/src/templates/opac/parts/record/copy_table.tt2:58
msgid "%1 (foreign item)"
msgstr "%1 (cizí exemplář)"

#: ../../Open-ILS/src/templates/opac/parts/place_hold.tt2:102
msgid "All Parts"
msgstr "Všechny části"

</code>


==== Translation workflow at Evergreen release ====

  - When new release is being prepared, the //POT// files are generated and imported into Evergreen translation project in Launchpad. The import to Launchpad happens usually at the time when Evergreen  beta is released.
  - The strings in Launchpad are translated to various languages. Also strings newly added to Evergreen can be added to Launchpad in the meantime, between beta release and X.Y.0 release. 
  - Before X.Y.0 release the new //PO// files are generated from the Launchpad translation data and are included into the release.

Build master of Evergreen release  is responsible for generating the POT and PO files.





==== Support for individual languages in Evergreen release ====
 
Currently there are over 30 Evergreen translation projects in Launchpad. However,  only languages meeting at least one of the following criteria are included into Evergreen release: 

  * At least 70 % of translation is complete
  * Translation has been updated within the past 12 months and at least 50 % is complete
  * It is known there is someone actively working on the translation
  * There is a known living Evergreen catalog using the particular language
  * The en-* variant of translations have an exception from criteria above as they are a special case (there is no need to translate all strings).

NOTE: These criteria are not a "law" and they can be changed in individual cases (exception can be make e.g, if only minor parts has been translated yet but local community exists and plans to test or implement Evergreen locale and language in a near future). Please, feel free to contact Evergreen translations coordinator [[mailto:cernin@jabok.cz | Eva Cerniňáková]] if you have any questions.


===== How to translate Evergreen (useful tips for translators) =====

As translation strings are separated from the "program" and  the same word or string can have more  meanings, it is sometimes tricky to understand what is the proper way to translate it. 
We recommend following:

  - **Understand what you translate.** \\ It is quite useful to have an idea  how  the software  really works. You can test the  Evergreen functionality by your own Evergreen  installation or you can use Evergreen community   [[ https://wiki.evergreen-ils.org/doku.php?id=community_servers | demo servers]].
  - **Leave the string untranslated until you are absolutely sure about its meaning.** \\ When using Evergreen, it is much less complicated to cope with English (untranslated) strings and messages then to come across wrong/misleading translation. E.g. the word "copy" usually means particular item of the document in Evergreen, but it can be used as a verb meaning to "reproduce" something. One English expression can also have various meanings in other languages etc. You can get some hints from: 
    - Notes to translators (denoted by  blue icons with "i")
    - String location (under the //New translation// field).  \\ E.g. information: //Located in ../../Open-ILS/src/templates/opac/register.tt2:63// means that the translated string occurs in //register.tt2// template file for OPAC, line 63 (and probably have something to do with user registration in OPAC).
  - ** Be consistent in used expressions** \\ Translate the same word or string always in the same way. It is good to make some "revisions" time to time. You can use [[https://docs.google.com/spreadsheets/d/13YvSic49TI8g-zyE4dn1QXCvwqf1cXumKEhjEhcVvSg/edit?usp=sharing | list of Evergreen translation strings]] containing all English strings with name of the template, to identify quickly in which template the string occurs ((Note: The items  have been extracted from individual templates using  simple script. When an unexpected character (e.g., part of the code or variables) was used in translation string, it could affect the processing of the template. In such cases the item might exceptionally have been missing or inaccurate.))
  - **Recognize the background of translated expression.** \\ Translation strings contain e.g.: 
    - standardized terms used for MARC record description in Evergreen (it is good to have national MARC fields and terms translations at hand), 
    - terms used in ICT (like protocols names), 
    - SQL entities, 
    - names of countries and languages, 
    - names of providers etc.
  - **Pay attention to symbols representing specific characters** \\ It is necessary to add  newline or space to your translation  if it is used in the original string.
  - **In some cases, some parts of strings should not be translated. It concerns particularly:** \\ 
     -  Data placeholders and variable names (e.g., %s or $name or ${name} etc.)
     - Formatting(HTML)/XML tags 
     - Program parameters etc.
  - ** After you have translated a string, read it again.** \\ It is good practice to review the translation and see possible mistyping or errors, missing punctuation etc.
  - **Be brief.** \\ When possible, use brief expressions in the translation. In some cases, too long expression could confuse the user, make the menu too wide or button too robust etc. However, in some cases, this does not apply, see following:
  - **Translation must be understandable -  adapt them to the language and the local context.** \\ Sometimes it is not the best choice to translate  string "word for word". In some cases it is better to use terms that slightly differ from the original but are commonly used in the language you are translating to. It might be also useful to  change the order of the words or sentences for given language, even exceptionally to add  kind of "explanation" for the better understanding of the context etc.
  - **Always use the Evergreen main series for the translations.** 
  - **The most important templates are listed first in Launchpad.** \\  Start with //tpac// template (which contains strings used in Online public Evergreen catalog). It can be a good start for testing the translations and functionality.
  - ** Be in touch with other translators. **

More information available at [[https://help.launchpad.net/Translations/Guide |Launchpad]]

If you have any questions, please, contact Evergreen translations coordinator [[ mailto:cernina@jabok.cz | Eva Cerniňáková]].


===== Updating translations in Evergreen using current translations from Launchpad =====

Due to Evergreen release workflow/schedule it may happen, that some language strings in TPAC or in Web staff client are not available in locale language even if the particular string  has been already translated  in Launchpad. It may also be necessary to test translations for a new release (e.g. beta) when translations have not been yet added from Launchpad to Evergreen release. In such cases it is possible to manually replace the PO file in Evergreen by up-to-date PO file downloaded from Launchpad. 

**Recommended practice:**
  - Visit the Evergreen translation site in Launchpad (https://translations.launchpad.net/evergreen)
  - Select required language (e.g. Czech or Spanish ….)
  - Open the  //tpac//  template  and  then select option //Download translation// (note: in order to be able to download the translation file you need to be logged in to Launchpad).
  - Select //PO format// and submit the //Request for download// button ((You can also request for download of [[https://translations.launchpad.net/evergreen/master/+export | all existing templates and languages at once]])). The download link will be sent You to email address provided. 
  - Download the file and rename it according to the desired language (e.g., cs-CZ.po for Czech or  es-ES.po for Spanish)  
  - Copy the downloaded file to  /openils/var/template/data/locale. It is a good practice to backup the original PO file before.
Changes require web server reload to take effect (as root run the command //service apache2 restart//)

Analogically, to update the web staff client translations, download the translation template //webstaff// and copy it to ///openils/var/template/data/locale/staff//.

NOTE: It is necessary to set specific  language previously - see the documentation: [[https://docs.evergreen-ils.org/docs/latest/admin_initial_setup/designing_your_catalog.html#setting_a_default_language_and_adding_optional_languages | Setting a default language and adding optional languages]].

===== Making the custom string in TPAC translatable. =====

To make the custom string translatable  (e.g., links in top or bottom navigation in OPAC, or any other kind of custom information on catalog homepage etc.), it is necessary to insert the text to TPAC template  as translatable string and add the custom strings to the PO containing translations in given language.


As Evergreen supports multiple languages, it is important, that any customization to Evergreen’s default text  uses the localization function. To make the custom string translatable, the string must be in English and must be surrounded by   **[% l('**   ** ') %]**  (( The [% ... %] signifies a TT block, which can contain one or more TT processing instructions. l(" ... "); is a function that marks text for localization (translation). ))




For example if you want to add  the custom translatable  link to the Evergreen top navigation bar (template openils/var/template/opac/parts/topnav_links.tt2), the added link will look like this:
            <a href="http://example.com">[% l('Example text') %]</a>
For more information see the documentation: [[http://docs.evergreen-ils.org/2.10/_changing_some_text_in_the_tpac.html | Changing some text in the TPAC]].

Note: It is recommended to use use template overriding rather than touching the installed templates. For more information 
see the documentation: 
  * [[http://docs.evergreen-ils.org/2.11/_designing_your_catalog.html#_configuring_and_customizing_the_public_interface | Configuring and customizing the public interface]] 
  *  [[http://docs.evergreen-ils.org/2.11/_how_to_override_templates.html |How to override templates]].





==== Adding the custom string to PO file ====

After you have added custom texts in translatable form to a TT2 template, you need to add the custom strings and its translations to the PO file containing the translations (the PO files are stored  in  ///openils/var/template/data/locale/ // )

Note: It is good practice to save backup copy of the original PO file before changing it.
=== Editing PO file ===

  * The English expressions must be identified by //msgid// and  enclosed in “  “. 
  * The translation must be identified by //msgstr// and enclosed in “  “ . 
  * It is recommended to  add a note in which template and on which line the particular  string is located. The lines with notes must be marked as comments (i.e., start with //#//) 

**Example:** Czech texts inserted to cs.CZ.po  (texts are used in TT2 files for TPAC interface customization)
 

<code>
# ---------------------------------------------------------------------
# The lines below contains the custom strings manually added to catalog
# ---------------------------------------------------------------------

#: ../../Open-ILS/src/custom_templates/opac/parts/topnav_links.tt2:1
msgid "Union Catalog of the Czech Republic"
msgstr "Souborný katalog České republiky"

#: ../../Open-ILS/src/custom_templates/opac/parts/topnav_links.tt2:1
msgid "Uniform Information Gateway "
msgstr "Jednotná informační brána"

</code>   

**Example of living Evergreen catalog using translatable custom strings:**

http://knihovna.jabok.cuni.cz (Knihovna Jabok, Czech Republic)

===== Adding Translations Through Angular Interfaces =====

The newer Angular administration interfaces provide a button to add translations (for example, the MARC Coded Value Map controls the Audience dropdown fields in the OPAC advanced search), but you will need to edit a file in order to enable it for each language. 

  - Edit Open-ILS/src/eg2/src/environments/environment.prod.ts
  - Modify the locales array (eg, locales: ['en-US','fr-CA','es-ES']
  - Recompile Angular: ng build --prod

===== Additional information =====

Information on Evergreen 
[[evergreen-admin:customizations:i18n|Internationalization (I18N), Localization (L10N), and Globalization (G11N)]]



{{tag>i18n devdocs}}