\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename wmaker_i18n.info @settitle Window Maker Internationalisation 1.0 @c %**end of header @c This documentation is written in Texinfo format: @c https://www.gnu.org/software/texinfo/manual/texinfo/ @c @c The reference checker is the GNU texi2any tool, which can be invoked like this: @c texi2any --plaintext --no-split --verbose Translations.texi @c @c If you modify this file, you may want to spell-check it with: @c aspell --lang=en_GB --mode=texinfo check Translations.texi @c @c The length of lines in this file is set to 100 because it tends to keep sentences together @c despite the embedded @commands{}; @c @c It is generally considered good practice for Tex and Texinfo formats to keep sentences on @c different lines, using the fact that in the end they will be merged in paragraph anyway, because @c it makes the patchs clearer about where the changes actually are. @finalout @set version git#next @c ---------------------------------------------------------------------------------- Title Page --- @copying @noindent This manual is for @sc{Window Maker} window manager, version @value{version}. @noindent Copyright @copyright{} 2015 The Window Maker Team. @quotation This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program, see file COPYING for details. @end quotation @end copying @titlepage @title Window Maker Internationalisation @subtitle A guide to enable support for language translations @subtitle in @sc{Window Maker}. @author Christophe CURIS @page @vskip 0pt plus 1filll @insertcopying @sp 1 Published by The Window Maker team on @today{}. @end titlepage @c ---------------------------------------------------------------------------- Table of Content --- @node Top @ifnottex @top Window Maker Internationalisation A guide to enable support for language translations in @sc{Window Maker}. @end ifnottex @contents @ifnottex @sp 1 This manual is for Window Maker, version @value{version}. @end ifnottex @menu * Enabling Languages support:: How to compile Window Maker with i18n support * Choosing the Language:: When installed, how to run wmaker with your language * Troubleshooting:: Some points to check if you have problems @end menu @c ------------------------------------------------------------------ Enabling Languages support --- @node Enabling Languages support @chapter Enabling Languages support @sc{Window Maker} has the possibility to be translated in many languages, but by default none of them will be installed, and the support for translation will not be compiled. To enable the translation capabilities, you have to specify which language(s) you want to be installed: this is done with the variable @env{LINGUAS} when running the @command{configure} script. This variable should contain the space-separated list of languages you want to install. You could for instance enable both French (@code{fr}) and Dutch (@code{nl}) with this: @example ./configure LINGUAS="fr nl" @end example You can of course add any other option that you want to the @command{configure} command. From the moment you specify the variable, the @command{configure} script will check that you have the appropriate dependencies for this (basically the @code{gettext} function and the @code{libintl} library); when you run @command{make} to compile the project, it will also compile the translation (@code{mo} files) for the language(s) you asked (if available, of course), and during @command{make install} it will install them in the usual directory. The installation directory can be changed with the standard option @option{--localedir} to the @command{configure} script, the default path being @file{@emph{}/share/locale/@emph{}/LC_MESSAGES}). @c ----------------------------------------------------------------- List of supported Languages --- @section Getting the list of supported languages The naming convention for the languages follows the @cite{ISO 639-1} standard, for which you can find a summary list in the @uref{https://www.gnu.org/software/gettext/manual/html_node/Usual-Language-Codes.html, GNU gettext manual}. But as @sc{Window Maker} does not support all of them, the @command{configure} script will print a warning for each language you specify that it does not know, and sum up at the end the list of enabled languages that will be installed. There is a non-standard possibility to set @env{LINGUAS} to @code{list}, in which case the @command{configure} script will provide you the list of languages it supports, and stop: @example ./configure LINGUAS="list" @end example There is also another non-standard possibility to enable all the languages that @sc{Window Maker} supports by setting @env{LINGUAS} to @code{*}. This is an internal trick implemented so the development team can have the command @command{make distcheck} include some checks on translations: @example ./configure LINGUAS='*' @end example @c ---------------------------------------------------------------------- Translations for Menus --- @section Translations for Menus In order to propose an @emph{Application Menu} (also called @emph{Root Menu}) that is also translated in the language of the interface, @sc{Window Maker} implements two complementary mechanisms: The first, always enabled when i18n support is enabled, is to look for the menu file containing the name of the locale. For example, if the file is called @file{menu} and the language is set as @env{LANG=fr_FR.utf-8}, then @sc{Window Maker} will search for, and use the first match found: @itemize @item @code{menu.fr_FR.utf-8} @item @code{menu.fr_FR} @item @code{menu.fr} @item @code{menu} @end itemize The second possibility, which is not enabled by default, is to be able to use a custom @file{po} file which contains the translations for the text of the menu. This feature is enabled at compile time, using the option @option{--with-menu-textdomain} to the @command{configure} script. For example, if you specify: @example ./configure --with-menu-textdomain=WMMenu @end example @noindent then the translations for the menu will be searched in the file @file{WMMenu.mo} located at the standard location, the default path being @file{@emph{}/share/locale/@emph{}/LC_MESSAGES/@emph{WMMenu}.mo}. If you do not enable the feature (the default behaviour, or with an explicit @option{--without-menu-textdomain}), then @sc{Window Maker} will @b{not} try to translate the strings, even using its own domain file (@file{WindowMaker.mo}). @c --------------------------------------------------------------------- LINGUAS at system level --- @section Setting @env{LINGUAS} at system level As the variable @env{LINGUAS} is quite standard, you also have the possibility to set its value in the @file{config.site} file for @sc{Autoconf}. This file can be placed in one of these paths: @itemize @bullet @item @file{@emph{}/share/config.site} @item @file{@emph{}/etc/config.site} @end itemize This way, the same language list will be used for all the programs that use @sc{Autoconf} that you would compile. Please note that if you also specify a value on the command line, it will have precedence over the value in that file. @c ----------------------------------------------------------------------- Choosing the Language --- @node Choosing the Language @chapter Choosing the Language If you have compiled and installed @sc{Window Maker} with support for your language, the effective translation is done is the very same way as any other application on an @sc{Unix} system, you just have to set the shell variable @env{LANG} to your language before @command{wmaker} is started. In @command{sh} type of shell (@sc{sh}, @sc{ksh}, @sc{bash}, ...), this is done for example with (@code{fr} is for French): @example export LANG=fr @end example There is also a command line option @option{--locale} for @sc{Window Maker} which may be used to set the language: @example wmaker --locale fr @end example When using this option, @sc{Window Maker} will use the locale you specified, redefining the @env{LANG} environment variable to this value so all program started from @sc{Window Maker} will inherit its value. If your system is using @sc{systemd}, you can also configure the locale at system level using the command: @example localectl set-locale LANG=fr @end example You can check if the current value is properly supported with the command: @example locale @end example If this does not work, you may need first to activate the support for your locale in the system; you can get the list of currently enabled locales with the command: @example locale -a @end example You should be able to enable a new language support by editing the file @file{/etc/locale.gen} to uncomment the locale(s) you need (by removing the @code{#} character and space(s) in front of it, and by running the command @command{locale-gen} as root. For further information, you may wish to read dedicated documentation, for example from @uref{http://tldp.org/HOWTO/HOWTO-INDEX/other-lang.html, the Linux Documentation Project} or through pages like @uref{http://www.shellhacks.com/en/HowTo-Change-Locale-Language-and-Character-Set-in-Linux,Shell Hacks' note on Changing Locale}. @c ----------------------------------------------------------------------------- Troubleshooting --- @node Troubleshooting @chapter Troubleshooting If I18N support does not work for you, check these: @itemize @minus @item the @env{LANG} environment variable is set to your locale, and the locale is supported by your OS's locale or X's locale emulation. you can display all supported locales by executing "@command{locale -a}" command if it is available; you can check if your locale is supported by X's locale emulation, see @file{/usr/share/X11/locale/locale.alias} @item check if you are using an appropriate fonts for the locale you chose. If you're using a font set that has a different encoding than the one used by @sc{Xlib} or @sc{libc}, bad things can happen. Try specifically putting the encoding in the @env{LANG} variable, like @code{ru_RU.KOI8-R}. Again, see @file{/usr/share/X11/locale/locale.alias} @item the fonts you're using support your locale. if your font setting on @file{$HOME/GNUstep/Defaults/WindowMaker} is like... @example WindowTitleFont = "Trebuchet MS:bold:pixelsize=12"; MenuTitleFont = "Trebuchet MS:bold:pixelsize=12"; @end example then you can't display Asian languages (@code{ja}, @code{ko}, @code{ch}, ...) characters using @code{Trebuchet MS}. A font that is guaranteed to work for any language is @code{sans} (or @code{sans-serif}). @code{sans} is not a font itself, but an alias which points to multiple fonts and will load the first in that list that has the ability to show glyphs in your language. If you don't know a font that is suited for your language you can always set all your fonts to something like: @example "sans:pixelsize=12" @end example However, please note that if your font is something like: @example "Trebuchet MS,sans serif:pixelsize=12" @end example this will not be able to display Asian languages if any of the previous fonts before sans are installed. This is because unlike the proper font pickup that @code{sans} guarantees for your language, this construct only allows a font fallback mechanism, which tries all the fonts in the list in order, until it finds one that is available, even if it doesn't support your language. Also you need to change font settings in style files in the @file{$HOME/Library/WindowMaker/Style} directory. @item the @env{LC_CTYPE} environment variable is unset or it has the correct value. If you don't know what is the correct value, unset it. @end itemize @c ------------------------------------------------------------------------------------- The End --- @bye