[sane-devel] SANE2 proposal

[Henning Meier-Geinitz]

Hi,

On Mon, Apr 15, 2002 at 11:38:34PM +0200, Oliver Rauch wrote:
> I included this and several other suggestions in the SANE2 proposal 0.06
> that can be dwonloaded from:
> 
> 	http://www.xsane.org/sane2/index.html
> 
> Suggestions, comments and help are welcome!!!

Concerning Internationalization: Please find attached a diff and the
complete text for a slightly modified chapter. I mostly changed the
wording/spelling etc. a bit. Please read it and just ignore the
changes you don't like. 

I think we should create an own function that returns the gmo (?)
file. We shouldn't mixe this with the function for getting
documentation because of the different file formats and scope.
Maybe something like:

SANE_String sane_get_translation_table (SANE_String_Const lang)

Returns the GNU gettext gmo file for language lang (e.g., "de") or
NULL, if the gmo file isn't available or any other error ocurred.
The table is guaranteed to remain valid until
sane_get_translation_table is called again the backend is exited.

Bye,
  Henning
-------------- next part --------------
--- sane2-0.06.tex	Mon Apr 22 18:58:18 2002
+++ sane.tex	Mon Apr 22 20:04:36 2002
@@ -1139,38 +1139,38 @@
 
 \subsection{Internationalization}\label{sec:i18n}
 \begin{changebar}
-All backend texts should be written in english.
+All backend texts should be written in English.
 Localization (translation of backend texts) has to be done
-in the frontend. To automatically prepare translation tables
-(e.g. english to german) it is necessary to mark the texts
+by the frontend. To automatically prepare translation tables
+(e.g., English to German) it is necessary to mark the texts in the backend
 that shall be translated.
 
-\subsubsection{How is a text marked for translation}
+\subsubsection{Marking Texts for Translation}
 
 The keyword \code{SANE\_I18N} is used to mark a text for translation.
-\code{SANE\_I18N} has to be defined as a dummy prototype:
+\code{SANE\_I18N} has to be defined as a dummy macro:
 
-  \begin{quote}
+\begin{quote}
 \begin{verbatim}
 #ifndef SANE_I18N
 #  define SANE_I18N(text) text
 #endif
 \end{verbatim}
-  \end{quote}
+\end{quote}
 
-You should not mark prototypes or variables with \code{SANE\_I18N}
+Macros or variables shouldn't be marked by \code{SANE\_I18N}
 because it is not possible (or very hard) to find out the
-texts that are covered by prototypes (\verb|SANE_I18N(START_SCAN_TEXT)|) and
-variables (\verb|SANE_I18N(option[7].name)|).
+texts that are covered by macros (e.g., \verb|SANE_I18N(START_SCAN_TEXT)|) and
+variables (e.g., \verb|SANE_I18N(option[7].name)|).
 
-A correct marked text can look like this:\\
-\verb|snprintf(buf, sizeof(buf), SANE_I18N("Start scan")|\\
+A properly marked text can look like this:\\
+\verb|snprintf(buf, sizeof(buf), SANE_I18N("Start scan"))|\\
 or\\
 \verb|#define START_SCAN_TEXT SANE_I18N("Start scan")|.\\
-It also is allowed to mark texts in structs because the
-prototype \code{SANE\_I18N} has no effect to the compiler.
+It is also allowed to mark texts in structs because the
+prototype \code{SANE\_I18N} has no effect on compilation.
 
-\subsubsection{Which texts shall be marked for translation?}
+\subsubsection{Translatable Texts}
 All option texts that are visible for the user should be marked for
 translation. This is:
 \begin{itemize}
@@ -1187,31 +1187,29 @@
 Please also do not mark any error or debug messages that are
 displayed by the backend.
 
-\subsubsection{File formats and translation functions}
-The recommended file formats for translation tables are the \code{po} files
-and \code{mo} or \code{gmo} files.
-The po file contains the original text marked with the keyword \code{msgid}
-and the translated text marked with the keyword \code{msgstr}.
-A \code{po} file that contains all needed \code{msgid}s can be created
-e.g. by the gnu gettext tool \verb|xgettext| with the option
-\verb|-k SANE_I18N|.
-The translator adds the translated texts to the \code{po} files.
-The gettext tool \code{msgfmt} converts the \code{po} files to the
-\code{mo} or \code{gmo} files.\\
+\subsubsection{File Formats and Translation Functions}
+The recommended file formats for translation tables are the GNU gettext
+\code{po} files and \code{mo} or \code{gmo} files.  The \code{po} file
+contains the original text marked with the keyword \code{msgid} and the
+translated text marked with the keyword \code{msgstr}.  A \code{po} file that
+contains all needed \code{msgid}s can be created e.g. by the GNU gettext tool
+\verb|xgettext| with the option \verb|-k SANE_I18N|.  The translator adds the
+translated texts to the \code{po} files.  The gettext tool \code{msgfmt}
+converts the \code{po} files to the
+binary \code{mo} or \code{gmo} files.\\
 
-Translation is done in the frontend. A backend has nothing
-to do with the translation of texts.
+The translation itsself is done in the frontend. A backend isn't involved
+in the actual translation of texts.
 The frontend should use the function \code{gettext}
 to translate the texts. This e.g. can look like this:\\
 \verb|snprintf(buf, sizeof(buf), gettext("english text"));|
 
 If a frontend author decides to use translation functions that
-need different translation tables, then the frontend is
+don't understand the GNU gettext translation tables, then the frontend is
 responsible to create/convert the translation tables.
-In this case it should use the \code{po} files to create its
-own translation tables from it.\\
+In this case it should derive its own translation tables from the \code{po}
+files.
 
-Note that it is strongly recommended to use the gettext tools.
 \end{changebar}
 
 
-------------- next part --------------
\subsection{Internationalization}\label{sec:i18n}
\begin{changebar}
All backend texts should be written in English.
Localization (translation of backend texts) has to be done
by the frontend. To automatically prepare translation tables
(e.g., English to German) it is necessary to mark the texts in the backend
that shall be translated.

\subsubsection{Marking Texts for Translation}

The keyword \code{SANE\_I18N} is used to mark a text for translation.
\code{SANE\_I18N} has to be defined as a dummy macro:

\begin{quote}
\begin{verbatim}
#ifndef SANE_I18N
#  define SANE_I18N(text) text
#endif
\end{verbatim}
\end{quote}

Macros or variables shouldn't be marked by \code{SANE\_I18N}
because it is not possible (or very hard) to find out the
texts that are covered by macros (e.g., \verb|SANE_I18N(START_SCAN_TEXT)|) and
variables (e.g., \verb|SANE_I18N(option[7].name)|).

A properly marked text can look like this:\\
\verb|snprintf(buf, sizeof(buf), SANE_I18N("Start scan"))|\\
or\\
\verb|#define START_SCAN_TEXT SANE_I18N("Start scan")|.\\
It is also allowed to mark texts in structs because the
prototype \code{SANE\_I18N} has no effect on compilation.

\subsubsection{Translatable Texts}
All option texts that are visible for the user should be marked for
translation. This is:
\begin{itemize}
\item
member \code{title}
\item
member \code{desc}
\item
member \code{string\_list}
\end{itemize}
of \code{SANE\_Option\_Descriptor}.

It is not allowed to mark/translate member \code{name}.
Please also do not mark any error or debug messages that are
displayed by the backend.

\subsubsection{File Formats and Translation Functions}
The recommended file formats for translation tables are the GNU gettext
\code{po} files and \code{mo} or \code{gmo} files.  The \code{po} file
contains the original text marked with the keyword \code{msgid} and the
translated text marked with the keyword \code{msgstr}.  A \code{po} file that
contains all needed \code{msgid}s can be created e.g. by the GNU gettext tool
\verb|xgettext| with the option \verb|-k SANE_I18N|.  The translator adds the
translated texts to the \code{po} files.  The gettext tool \code{msgfmt}
converts the \code{po} files to the
binary \code{mo} or \code{gmo} files.\\

The translation itsself is done in the frontend. A backend isn't involved
in the actual translation of texts.
The frontend should use the function \code{gettext}
to translate the texts. This e.g. can look like this:\\
\verb|snprintf(buf, sizeof(buf), gettext("english text"));|

If a frontend author decides to use translation functions that
don't understand the GNU gettext translation tables, then the frontend is
responsible to create/convert the translation tables.
In this case it should derive its own translation tables from the \code{po}
files.

\end{changebar}


\section{Operations}