====== Guide for SavaPage Translators ======

At this moment there is no Web front-end available like [[https://webtranslateit.com|WebTranslateIt]]. So, translations must be done via the core ''git'' interface of the [[https://gitlab.com/savapage-i18n|savapage-i18n-*]] projects.

The SavaPage Translation Manager (STM) will be your guide during the ongoing translation process. The STM will communicate the //sequence// and //priority// of files to translate.

| STM: [[https://www.datraverse.com/keys|Rijk Ravestein]]|
| Do //not// start on your own, but wait for instructions by the STM. |

===== Step 1: Register as GitLab user (optional) =====

If agreed with the STM:
  - [[https://gitlab.com/users/sign_in|Register]] as GitLab user, and send Name and User ID to the STM.
  - STM will add you as Developer to your "savapage-i18n-xx" project.

===== Step 2: Clone savapage-i18n-en =====

The English [[https://gitlab.com/savapage-i18n/savapage-i18n-en|savapage-i18n-en]] Library is the source of all ''savapage-i18n-*'' translations: clone this library for local reference.

<code bash>
# public access
git clone https://gitlab.com/savapage-i18n/savapage-i18n-en.git
# or, if you are a committer and assigned to edit...
git clone git@gitlab.com:savapage-i18n/savapage-i18n-en.git

# Switch to develop branch
cd savapage-i18n-en
git checkout develop

# Keep your source up-to-date
git pull
</code>

===== Step 3: Clone savapage-i18n-xx =====

<code bash>
# Since you are a committer ...
git clone git@gitlab.com:savapage-i18n/savapage-i18n-xx.git

# Switch to develop branch
cd savapage-i18n-xx
git checkout develop

# Keep your source up-to-date, when more translators are active!!
git pull
</code>

| The ''savapage-i18n-xx'' directory is the home of your translated files |

===== Step 4: Start translating =====

==== How does a translation look like? ====

Your ''savapage-i18n-xx'' translation will eventually be a complete mirror of the ''savapage-i18n-en'' reference. This means that each English ''path/*.xml'' has an ''xx'' translated ''path/*_xx.xml'' version in your ''savapage-i18n-xx'' directory.

Compared to its English counterpart, each ''*_xx.xml'' file has extra information about the translator in its header, as can be seen in the template below.

<code xml template_xx.xml>
<?xml version="1.0" encoding="UTF-8"?>
<!--
This file is part of the SavaPage project <https://savapage.org>
Copyright (c) 2021 Datraverse B.V. | Author: Rijk Ravestein 

SPDX-FileCopyrightText: © 2021 Datraverse BV <info@datraverse.com>
SPDX-License-Identifier: AGPL-3.0-or-later

SavaPage is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.

Translator: Your Name <you@example.com>
-->            
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>

    <entry key="a-key">A translation with a first {0} and second {1} 
         placeholder.</entry>

</properties>
</code>

==== Procedure ====

<code bash>
# A first translation starts by copying the English counterpart

# For plain message files
cp ./savapage-i18n-en/some-path/File.xml ./savapage-i18n-xx/same-path/File_xx.xml

# For web pages
cp ./savapage-i18n-en/some-path/Page.properties.xml ./savapage-i18n-xx/same-path/Page_xx.properties.xml

# Edit File_xx.xml according to the i18n template and translate the strings. 

# Copy/Edit some more files ... 
</code>

When done, if you are a GitLab user with Developer rights ...
<code bash>
# ... execute 
git add  # for each file

# Files already part of git can just be edited.

# Complete an assignment with a 
git commit 
git push

# Contact the STM so he can do a ...
git pull
# ... build the savapage-i18n-xx.jar and inspect the result.
</code>

If you do //not// have Git Developer rights, send a zipped copy of your translations to the STM, which can then put the files in the repository for you.


==== See your translation in action ====

There are several possibilities, as communicated by the STM:

  - Your translation is part of a new installation binary [[https://www.savapage.org/download/snapshots/|snapshot]] : //install the snapshot to see the results//.
  - A new snapshot ''savapage-i18n-xx.jar'' file is available: //use this new one to overwrite the one in your own SavaPage installation//.

When the ''savapage-i18n-xx'' project is part of your overall SavaPage build environment or IDE (Eclipse): 
  * Rebuild and deploy to your own test environment, or run SavaPage in the IDE.

An alternative low threshold way to get started is by using the SavaPage [[https://www.savapage.org/docs/manual/ch-customization.html#ch-custom-webapp-i18n|Custom i18n]] feature with the *.xml files from the [[https://gitlab.com/savapage-i18n/savapage-i18n-en|savapage-i18n-en]] repository as a reference. In this way your translation is directly visible in SavaPage.