parts/Translations.tex

   1 \chapter{Translations}%
   2 \label{cha:translations}
   3
   4 There are several \textit{po} files for various languages to make \CGG{} more usable for non-English
   5 countries.  These are listed below along with the po file name with the translations, the frequency
   6 of updates, and date of last update as of this writing.
   7
   8 \begin{tabular}{llll}
   9 \hline
  10         English& cin.po& Baseline &(en\_US) \\
  11         French& fr.po&  Updated often& Last update 2019 May\\
  12         German&  de.po& Updated often& Last update 2019 December\\
  13         Russian& ru.po& Updated often& Last update 2019 October\\
  14         Spanish& es.po& Updated often& Last update 2021 July\\
  15 \\
  16         Basque& eu.po&  From CV with Google Translate & Last update 2016 October\\
  17         Italian&it.po&  From CV with Google Translate & Last update 2016 October\\
  18         Norwegian& nb.po& From CV with Google Translate & Last update 2016 October\\
  19         Portuguese& pt.po& From CV with Google Translate& Last update 2016 October \\
  20         Slovenian& sl.po & From CV with Google Translate& Last update 2016 October \\
  21 \\
  22         Chinese& zh.po& Only Google Translate & 2016 October\\
  23         Greek&  el.po& Only Google Translate & 2016 October\\
  24         Hindi& hi.po& Only Google Translate & 2016 October\\
  25         Hungarian& hu.po& Only Google Translate & 2021 October\\
  26         Japanese& ja.po& Only Google Translate & 2016 October \\
  27         Korean& ko.po& Only Google Translate    & 2016 October \\
  28         Ukrainian& uk.po & Only Google Translate & 2016 October \\
  29         Vietnamese& vi.po& Only Google Translate & 2016 October \\
  30 \hline
  31 \end{tabular}
  32
  33 A program, \textit{xlat.C}, assists in providing several variations of text files that can be used in order to allow anyone to help make meaningful translations.  All of the \textit{po} files are located in \CGG{}’s \texttt{/po} subdirectory. There are 3 different ways to proceed described below.
  34
  35 Because \CGG{} frequently is changing, it is a good idea to start by building a new \texttt{cin.po} file which contains the latest messages/words in English to be translated, along with a comment line of the routine name and line number.  To create this, run the following lines from a window:
  36
  37 \begin{lstlisting}[numbers=none]
  38 cd /{your top level cinelerra directory}
  39 ./po/xlat.sh > /tmp/cin.po
  40 \end{lstlisting}
  41
  42 \begin{description}
  43         \item[Method 1]  use the freely-available \textit{poedit} program to provide translations to the current \textit{xx.po} where xx is your language such as \texttt{fr.po}, \texttt{de.po}, \texttt{ru.po}, etc.  The drawback to this is that \textit{xx.po} files are not recreated monthly so they do not have all of the newest phrases included.
  44         \item[Method 2] using \textit{msgmerge} is probably the simplest method for user translation.
  45 \end{description}
  46
  47 To use the msgmerge command after creating a new cin.po as suggested previously:
  48
  49 \begin{lstlisting}[numbers=none]
  50 cd /{your top level cinelerra directory}
  51 ./po/xlat.sh > /tmp/cin.po                             # use /tmp as a temporary place
  52 cp /{your cinelerra directory}/po/xx.po /tmp/xx.po     # substitute your language for x
  53 msgmerge -U /tmp/xx.po /tmp/cin.po                    # xx.po will be overwritten to include updates
  54 \end{lstlisting}
  55
  56 Then use any editor or poedit to provide messages/words translations in the new xx.po file.
  57
  58 \begin{description}
  59         \item[Method 3 ] using \textit{xlat.C} program is the most versatile with a variety of features.  When a non-existent language translation is first set up, you would want to use this methodology to get started.
  60 \end{description}
  61
  62 To use the \textit{xlat.C} program, first compile it with \texttt{c++ xlat.C}.  You can see the usage help here:
  63
  64 \begin{lstlisting}[numbers=none]
  65         ./a.out
  66 list csv    ./a.out csv < data.csv > data.po
  67 list po     ./a.out po < data.po > data.csv
  68 list po     ./a.out dups < data.po
  69 list po     ./a.out nodups < data.po
  70 get strings ./a.out key  < xgettext.po
  71 gen xlation ./a.out xlat   xgettext.po xlat.csv
  72 gen xlation ./a.out xlat - text,xlat ... < xgettext.po
  73 \end{lstlisting}
  74
  75 This program has 6 commands where the desired command is the first parameter to a.out.:
  76
  77 \begin{enumerate}
  78         \item \textit{csv} = comma separated value file; to recreate a po from a csv file.
  79         \item \textit{po}  = convert po to csv data;  for example, what you need to convert ru.po to ru.csv.
  80         You can even open the resulting *.csv in LibrOffice and update the \textit{key $\rightarrow$ value} replacements
  81         (fields separated by "," only and check quoted fields as text during import).  These results can
  82         be \textit{Saved As} a csv file, and then used by xlat.C to reformulate a \textit{po}.
  83         \item \textit{dups} = list only key/value items where either the \textit{key=value} or \textit{value=" "}.
  84         \item \textit{nodups} = list only key/value items where \textit{key$\ne$value} and \textit{value$\ne$" "}.
  85         \item \textit{key} = list cin.po key set.
  86         \item \textit{xlat} = overlay translation.  This is the most important use and is described next.
  87 \end{enumerate}
  88
  89 The xlat command line parameters specify a new cin.po template, usually created with xlat.sh, and a list of key/value files which are used to build a mapping for the desired translation.  The mapping files are added to the mapping in the order they appear on the command line, and any existing key is replaced with the newest definition; so typically the newest key/value data is last in the command parameters.
  90 Once the mapping is built, the first parameter which is the new po template is scanned and the keys it contains are used to find the latest mapping in the key/value files.  The new value replaces the existing value in the template.  For example, to overlay a new map onto an existing po using the Spanish es.po file and where cin.po represents the latest english words:
  91
  92 \begin{lstlisting}[numbers=none]
  93 c++ xlat.C
  94 ./a.out po < es.po > /tmp/es.csv
  95 ./a.out po < cin.po > /tmp/cin.csv
  96 ./a.out xlat cin.po /tmp/es.csv > /tmp/new_es.po
  97 \end{lstlisting}
  98
  99 The first run preserves the existing mapping of \texttt{es.po}, the second creates new mappings from \texttt{cin.po}, and the third merges the original and new mappings to create a po with new included/overriding \texttt{es.po}.
 100
 101 \paragraph{NOTE:} some words and abbreviations can lead to ambiguous language translations.  Therefore, the usage of C\_ and D\_ in the program code was added to represent Contextual and Definitional exceptions to the usual \_ and N\_ .  You will see the following:
 102
 103 \vspace{2ex} \texttt{C\_(“msgstr”)}  is translated to \texttt{D\_(“qual\#msgstr”)} by \textit{xlat.sh}, and invokes gettext with \texttt{msgid = “qual\#msgstr”}
 104
 105 \vspace{2ex} When no \textit{po} translation is supplied, the qual\# is removed, and only the default \textit{msgstr} text is displayed.   If a \textit{po} translation is defined for the current locale, then the translated\texttt{ msgid = “qual\#msgstr”} is used to access the translated msgstr.
 106
 107 \vspace{2ex} \noindent The default MSGQUAL is the basename of the C source file.  For the file \texttt{src\_file.C}, the default MSGQUAL is:
 108
 109 \vspace{2ex} \texttt{\# define MSGQUAL “src\_file”}
 110
 111 \vspace{2ex} \noindent It is used to define the qualifier needed to transform:
 112
 113 \vspace{2ex} \texttt{C\_(“str”)} to \texttt{D\_(“src\_file\#str”)}
 114
 115 \vspace{2ex} \noindent The resulting xlat.sh'd source is scanned by xgettext to create the initial cin.po.  In other words:
 116
 117 \vspace{2ex} \_(s) does normal international text translation as always -
 118
 119 \vspace{2ex} \noindent The msgid line is: msgid “s”
 120
 121 \vspace{2ex} \texttt{C\_(s)} makes it appear as if you used \texttt{D\_(“src\_file\#” s)} -
 122
 123 \vspace{2ex} \noindent The msgid line is:\texttt{ msgid “src\_file\#s”}
 124 If it does not translate, the default msgtext is \texttt{“s”}, not \texttt{“src\_file\#s”}
 125
 126 \vspace{2ex} \texttt{D\_(qual\#s)} tries to look up \texttt{\_(qual\#s)} -
 127
 128 \vspace{2ex} \noindent This msgid line is: \texttt{msgid “qual\#s”},
 129 If it does not translate, the default msgtext is \texttt{“s”}, not \texttt{“qual\#s”}
 130