#LyX 2.2 created this file. For more info see http://www.lyx.org/
\lyxformat 508
\begin_document
\begin_header
\save_transient_properties true
\origin unavailable
\textclass paper
\begin_preamble

\end_preamble
\use_default_options true
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman "default" "default"
\font_sans "default" "default"
\font_typewriter "default" "default"
\font_math "auto" "auto"
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100 100
\font_tt_scale 100 100
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\float_placement H
\paperfontsize default
\spacing single
\use_hyperref true
\pdf_bookmarks true
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder true
\pdf_colorlinks false
\pdf_backref false
\pdf_pdfusetitle true
\papersize default
\use_geometry false
\use_package amsmath 1
\use_package amssymb 1
\use_package cancel 1
\use_package esint 1
\use_package mathdots 1
\use_package mathtools 1
\use_package mhchem 1
\use_package stackrel 1
\use_package stmaryrd 1
\use_package undertilde 1
\cite_engine basic
\cite_engine_type default
\biblio_style plain
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date true
\justification true
\use_refstyle 1
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 3cm
\topmargin 3cm
\rightmargin 3cm
\bottommargin 3cm
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title
Translating Paperwork
\end_layout

\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Newpage newpage
\end_inset


\end_layout

\begin_layout Section
This is not the document you're looking for
\end_layout

\begin_layout Standard
\begin_inset Wrap figure
lines 0
placement o
overhang 0in
width "2.5cm"
status open

\begin_layout Plain Layout
\begin_inset Graphics
	filename img/droid.png
	width 2cm

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
This document describes how to translate the user interface of Paperwork
 in other languages.
 Unless this is what you want to do, this is not the document you're looking
 for.
\end_layout

\begin_layout Standard
\begin_inset Newpage newpage
\end_inset


\end_layout

\begin_layout Section
Requirements
\end_layout

\begin_layout Itemize
a GNU/Linux system (
\begin_inset CommandInset href
LatexCommand href
name "Ubuntu"
target "https://www.ubuntu.com/download"

\end_inset

, 
\begin_inset CommandInset href
LatexCommand href
name "Debian"
target "http://debian.org"

\end_inset

, 
\begin_inset CommandInset href
LatexCommand href
name "Fedora"
target "https://getfedora.org/"

\end_inset

, etc)
\end_layout

\begin_layout Itemize
\begin_inset CommandInset href
LatexCommand href
name "Git"
target "http://rogerdudler.github.io/git-guide/"

\end_inset


\begin_inset Separator latexpar
\end_inset


\end_layout

\begin_deeper
\begin_layout Verbatim

apt install git git-gui # Ubuntu/Debian
\end_layout

\end_deeper
\begin_layout Itemize
Intltool
\begin_inset Separator latexpar
\end_inset


\end_layout

\begin_deeper
\begin_layout Verbatim

apt install intltool  # Ubuntu/Debian
\end_layout

\end_deeper
\begin_layout Itemize
Basic knowledge of the shell
\end_layout

\begin_layout Section
Getting a copy of Paperwork
\end_layout

\begin_layout Subsection
Forking
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement h
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Graphics
	filename img/github_fork.png
	scale 50

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Forking Paperwork on GitHub
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
The repository 
\emph on
Paperwork
\begin_inset Foot
status open

\begin_layout Plain Layout

\emph on
https://github.com/jflesch/paperwork
\end_layout

\end_inset


\emph default
 contains the GTK+ user interface.
 You will need a copy of this repository on your Github account in order
 to submit a pull request later.
\end_layout

\begin_layout Standard
There are also strings in the backend
\begin_inset Foot
status open

\begin_layout Plain Layout
https://github.com/jflesch/paperwork-backend
\end_layout

\end_inset

 that must be translated.
\end_layout

\begin_layout Subsection
Downloading
\end_layout

\begin_layout Standard
You must have configured GitHub SSH access for these commands to work.
 You need the frontend and the backend.
\end_layout

\begin_layout Verbatim

# download a copy of Paperwork repository
\end_layout

\begin_layout Verbatim

$ git clone git@github.com:[your login]/paperwork.git
\end_layout

\begin_layout Verbatim

# download a copy of Paperwork's backend repository
\end_layout

\begin_layout Verbatim

$ git clone git@github.com:[your login]/paperwork-backend.git
\end_layout

\begin_layout Standard
If you already have a copy of Paperwork repository, you can simply update
 it.
 You have to update first the copy stored on your Github account.
 You can then use the following commands to update the copy on your computer:
\end_layout

\begin_layout Verbatim

$ cd paperwork
\end_layout

\begin_layout Verbatim

$ git pull
\end_layout

\begin_layout Verbatim

$ cd ../paperwork-backend
\end_layout

\begin_layout Verbatim

$ git pull
\end_layout

\begin_layout Subsection
Selecting the branch
\end_layout

\begin_layout Standard
In the repository, there are usually the following branches:
\end_layout

\begin_layout Itemize

\emph on
stable
\emph default
 : Matches the latest release version.
 May also include some bug fixes that will be included in the next update
 (x.y.z ; ex: 1.2.2).
 No new features allowed.
\end_layout

\begin_layout Itemize

\emph on
unstable
\emph default
 : Will become the next version (x.y.0 ; ex: 1.3.0) of Paperwork.
 New features go here.
 This branch hasn't been tested yet and things may be broken.
\end_layout

\begin_layout Itemize

\emph on
testing
\emph default
 : When the unstable branch contains all the wanted features, the branch
 
\emph on
testing
\emph default
 is created from the branch 
\emph on
unstable
\emph default
.
 Only bug fixes, translations updates and documentation updates are allowed
 in this branch.
 This branch is temporary and usually lives for about 1 month.
 After 1 month, the version is released, and this branch is merged in the
 branch 
\emph on
stable
\emph default
.
\end_layout

\begin_layout Standard
Translations updates are allowed on any branches.
 However, it is recommended to make translations on the branch 
\emph on
testing
\emph default
 while it exists.
 You have to 
\begin_inset CommandInset href
LatexCommand href
name "subscribe to the mailing-list"
target "https://github.com/jflesch/paperwork/wiki/Contact#mailing-list"

\end_inset

 to know when it is created or merged.
 If the branch 
\emph on
testing
\emph default
 doesn't exist at the moment, you're advised to work on the branch 
\emph on
unstable
\emph default
.
\end_layout

\begin_layout Verbatim

$ cd paperwork
\end_layout

\begin_layout Verbatim

$ git checkout [branch]  # switch the wanted branch
\end_layout

\begin_layout Verbatim

$ cd ../paperwork-backend
\end_layout

\begin_layout Verbatim

$ git checkout [branch]  # switch the wanted branch
\end_layout

\begin_layout Section
Translating
\end_layout

\begin_layout Subsection
Extracting the strings to translate
\end_layout

\begin_layout Standard
Strings to translate are in the program itself.
 They have to be extracted for translation.
 A script has been included in Paperwork repository for this purpose.
\end_layout

\begin_layout Standard
It will look for strings to translate in 2 packages:
\end_layout

\begin_layout Itemize
'paperwork' (frontend): It will look in the current directory for .py, and
 .glade files and extract strings from these files.
\end_layout

\begin_layout Itemize
'paperwork_backend': It will look for the source files (.py) of 'paperwork-backen
d' where the environment variable BACKEND_DIRECTORY points to.
 If this variable is not set, it will look for the source files where paperwork_
backend has been installed.
\end_layout

\begin_layout Verbatim

$ export BACKEND_DIRECTORY=../paperwork-backend
\end_layout

\begin_layout Verbatim

$ ./localize.sh upd-po
\end_layout

\begin_layout Standard
Strings to translate and their translations (if they already have one) are
 stored in the 
\emph on
locale/[language].po
\emph default
.
 You can use any file editor to modify this file (GEdit, Vim, etc).
 If there is no file for the language you want, please open a ticket on
 GitHub.
\end_layout

\begin_layout Subsection
Updating the translations
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement H
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Graphics
	filename img/translations.png
	scale 50

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
Example of .po file
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Here are the steps to follow:
\end_layout

\begin_layout Itemize
Open the .po file corresponding to your language (
\emph on
locale/fr.po
\emph default
 for French for instance)
\end_layout

\begin_layout Itemize
Look for the keyword 
\begin_inset Quotes eld
\end_inset


\emph on
fuzzy
\emph default

\begin_inset Quotes erd
\end_inset

 : When a string is tagged with the keyword 
\begin_inset Quotes eld
\end_inset


\emph on
fuzzy
\emph default

\begin_inset Quotes erd
\end_inset

, it means the string didn't have any translations yet, but intltool found
 one that is really close.
 It is 
\emph on
often wrong
\emph default
 !
\end_layout

\begin_layout Itemize
Look for 
\emph on
msgstr 
\begin_inset Quotes eld
\end_inset


\begin_inset Quotes erd
\end_inset


\emph default
.
 Strings that have an empty translation basically don't have one at all.
 This is the only indicator a string has been added to Paperwork and requires
 translations.
\end_layout

\begin_layout Standard
Strings and translations can be multi-lines.
\end_layout

\begin_layout Standard
Some strings can contain python format elements (
\begin_inset Quotes eld
\end_inset


\emph on
%s
\emph default

\begin_inset Quotes erd
\end_inset

, 
\begin_inset Quotes eld
\end_inset


\emph on
%d
\emph default

\begin_inset Quotes erd
\end_inset

, 
\begin_inset Quotes eld
\end_inset


\emph on
{}
\emph default

\begin_inset Quotes erd
\end_inset

, etc).
 Their order 
\emph on
cannot
\emph default
 be changed ! If it is a problem for you, please open a ticket on GitHub.
 The string can be changed to use labels, which will allow you to reorder
 the elements.
\end_layout

\begin_layout Standard
Mixes of singular and plural are hard to handled.
 If one them is too tricky for you to handle, please open a ticket on GitHub.
 Workarounds can be found.
\end_layout

\begin_layout Subsection
Compiling the translations
\end_layout

\begin_layout Standard
Translations must be compiled.
 It allows Paperwork (via gettext) to fetch them quickly at runtime.
\end_layout

\begin_layout Verbatim

$ ./localize.sh gen-mo
\end_layout

\begin_layout Standard
It will regenerate the .mo files in 
\emph on
locales/
\emph default
.
\end_layout

\begin_layout Subsection
Testing the translations
\end_layout

\begin_layout Standard
You can run Paperwork from your Git repository using the following command:
\end_layout

\begin_layout Verbatim

python3 src/launcher.py
\end_layout

\begin_layout Standard
Paperwork looks at the system settings to know which language must be used.
 If you want to try other ones, simply set the LANG environment variable.
\end_layout

\begin_layout Verbatim

$ LANG=C python3 src/launcher.py  # Original strings (English)
\end_layout

\begin_layout Verbatim

$ LANG=fr_FR python3 src/launcher.py  # French
\end_layout

\begin_layout Verbatim

$ LANG=de_DE python3 src/launcher.py  # German
\end_layout

\begin_layout Section
Adding a new language
\end_layout

\begin_layout Standard
To add a new language to Paperwork, only the script 
\emph on
localize.sh
\emph default
 must be modified to include this new language.
 If you're unsure how to do it, simply open a ticket on GitHub and it will
 be done for you.
\end_layout

\begin_layout Section
Submit the new translations
\end_layout

\begin_layout Subsection
Commit your translations
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement h
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset Graphics
	filename img/commit_translations.png
	scale 50

\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption Standard

\begin_layout Plain Layout
git gui
\end_layout

\end_inset


\end_layout

\begin_layout Plain Layout

\end_layout

\end_inset


\end_layout

\begin_layout Standard
You must first create a Git commit containing your translations.
 Beware that 
\emph on
localize.sh
\emph default
 always modifies all the .po and .mo files for all the languages, but you
 must commit 
\emph on
only
\emph default
 your own changes.
 The simplest way for that is to use the command '
\emph on
git gui
\emph default
'.
 It will clearly show you what you're adding to your commit.
\end_layout

\begin_layout Standard
Both .po and .mo files must be commited at the same time.
\end_layout

\begin_layout Standard
The commit message must indicate this is about updating the translations.
 Other than that, there are no specific rules.
\end_layout

\begin_layout Subsection
Pushing
\end_layout

\begin_layout Standard
You can then push your new commit to your repository on GitHub.
 Either click 
\begin_inset Quotes eld
\end_inset


\emph on
Push
\emph default

\begin_inset Quotes erd
\end_inset

 in 
\emph on
git gui
\emph default
, or use the command 
\begin_inset Quotes eld
\end_inset


\emph on
git push
\emph default

\begin_inset Quotes erd
\end_inset

 in the shell.
\end_layout

\begin_layout Subsection
Pull request
\end_layout

\begin_layout Standard
Go to 
\begin_inset CommandInset href
LatexCommand href
name "GitHub"
target "https://github.com"

\end_inset

 and create a 
\begin_inset CommandInset href
LatexCommand href
name "pull request"
target "https://help.github.com/articles/creating-a-pull-request/"

\end_inset

 for 
\emph on
jflesch/paperwork
\emph default
.
\end_layout

\end_body
\end_document
