--XsQoSWH+UP9D9v3l Content-Type: text/plain; charset=us-ascii Content-Disposition: inline
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 --XsQoSWH+UP9D9v3l Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="sane-i18n.diff" --- 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} --XsQoSWH+UP9D9v3l Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename=scratch \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} --XsQoSWH+UP9D9v3l--
