runtime/doc/mlang.txt

   1 *mlang.txt*     For Vim version 7.1.  Last change: 2008 Jun 08
   2
   3
   4                   VIM REFERENCE MANUAL    by Bram Moolenaar
   5
   6
   7 Multi-language features                         *multilang* *multi-lang*
   8
   9 This is about using messages and menus in various languages.  For editing
  10 multi-byte text see |multibyte|.
  11
  12 The basics are explained in the user manual: |usr_45.txt|.
  13
  14 1. Messages                     |multilang-messages|
  15 2. Menus                        |multilang-menus|
  16 3. Scripts                      |multilang-scripts|
  17
  18 Also see |help-translated| for multi-language help.
  19
  20 {Vi does not have any of these features}
  21 {not available when compiled without the |+multi_lang| feature}
  22
  23 ==============================================================================
  24 1. Messages                                             *multilang-messages*
  25
  26 Vim picks up the locale from the environment.  In most cases this means Vim
  27 will use the language that you prefer, unless it's not available.
  28
  29 To see a list of supported locale names on your system, look in one of these
  30 directories (for Unix):
  31         /usr/lib/locale ~
  32         /usr/share/locale ~
  33 Unfortunately, upper/lowercase differences matter.  Also watch out for the
  34 use of "-" and "_".
  35
  36                                             *:lan* *:lang* *:language* *E197*
  37 :lan[guage]
  38 :lan[guage] mes[sages]
  39 :lan[guage] cty[pe]
  40 :lan[guage] tim[e]
  41                         Print the current language (aka locale).
  42                         With the "messages" argument the language used for
  43                         messages is printed.  Technical: LC_MESSAGES.
  44                         With the "ctype" argument the language used for
  45                         character encoding is printed.  Technical: LC_CTYPE.
  46                         With the "time" argument the language used for
  47                         strftime() is printed.  Technical: LC_TIME.
  48                         Without argument all parts of the locale are printed
  49                         (this is system dependent).
  50                         The current language can also be obtained with the
  51                         |v:lang|, |v:ctype| and |v:lc_time| variables.
  52
  53 :lan[guage] {name}
  54 :lan[guage] mes[sages] {name}
  55 :lan[guage] cty[pe] {name}
  56 :lan[guage] tim[e] {name}
  57                         Set the current language (aka locale) to {name}.
  58                         The locale {name} must be a valid locale on your
  59                         system.  Some systems accept aliases like "en" or
  60                         "en_US", but some only accept the full specification
  61                         like "en_US.ISO_8859-1".
  62                         With the "messages" argument the language used for
  63                         messages is set.  This can be different when you want,
  64                         for example, English messages while editing Japanese
  65                         text.  This sets $LC_MESSAGES.
  66                         With the "ctype" argument the language used for
  67                         character encoding is set.  This affects the libraries
  68                         that Vim was linked with.  It's unusual to set this to
  69                         a different value from 'encoding'.  This sets
  70                         $LC_CTYPE.
  71                         With the "time" argument the language used for time
  72                         and date messages is set.  This affects strftime().
  73                         This sets $LC_TIME.
  74                         Without an argument both are set, and additionally
  75                         $LANG is set.
  76                         When compiled with the |+float| feature the LC_NUMERIC
  77                         value will always be set to "C", so that floating
  78                         point numbers use '.' as the decimal point.
  79                         This will make a difference for items that depend on
  80                         the language (some messages, time and date format).
  81                         Not fully supported on all systems
  82                         If this fails there will be an error message.  If it
  83                         succeeds there is no message.  Example: >
  84                                 :language
  85                                 Current language: C
  86                                 :language de_DE.ISO_8859-1
  87                                 :language mes
  88                                 Current messages language: de_DE.ISO_8859-1
  89                                 :lang mes en
  90 <
  91
  92 MS-WINDOWS MESSAGE TRANSLATIONS                         *win32-gettext*
  93
  94 If you used the self-installing .exe file, message translations should work
  95 already.  Otherwise get the libintl.dll file if you don't have it yet:
  96
  97         http://sourceforge.net/projects/gettext
  98
  99 This also contains tools xgettext, msgformat and others.
 100
 101 libintl.dll should be placed in same directory with (g)vim.exe, or some
 102 place where PATH environment value describe.  Message files (vim.mo)
 103 have to be placed in "$VIMRUNTIME/lang/xx/LC_MESSAGES", where "xx" is the
 104 abbreviation of the language (mostly two letters).
 105
 106 If you write your own translations you need to generate the .po file and
 107 convert it to a .mo file.  You need to get the source distribution and read
 108 the file "src/po/README.txt".
 109
 110 To overrule the automatic choice of the language, set the $LANG variable to
 111 the language of your choice.  use "en" to disable translations. >
 112
 113   :let $LANG = 'ja'
 114
 115 (text for Windows by Muraoka Taro)
 116
 117 ==============================================================================
 118 2. Menus                                                *multilang-menus*
 119
 120 See |45.2| for the basics, esp. using 'langmenu'.
 121
 122 Note that if changes have been made to the menus after the translation was
 123 done, some of the menus may be shown in English.  Please try contacting the
 124 maintainer of the translation and ask him to update it.  You can find the
 125 name and e-mail address of the translator in
 126 "$VIMRUNTIME/lang/menu_<lang>.vim".
 127
 128 To set the font (or fontset) to use for the menus, use the |:highlight|
 129 command.  Example: >
 130
 131         :highlight Menu font=k12,r12
 132
 133
 134 ALIAS LOCALE NAMES
 135
 136 Unfortunately, the locale names are different on various systems, even though
 137 they are for the same language and encoding.  If you do not get the menu
 138 translations you expected, check the output of this command: >
 139
 140         echo v:lang
 141
 142 Now check the "$VIMRUNTIME/lang" directory for menu translation files that use
 143 a similar language.  A difference in a "-" being a "_" already causes a file
 144 not to be found!  Another common difference to watch out for is "iso8859-1"
 145 versus "iso_8859-1".  Fortunately Vim makes all names lowercase, thus you
 146 don't have to worry about case differences.  Spaces are changed to
 147 underscores, to avoid having to escape them.
 148
 149 If you find a menu translation file for your language with a different name,
 150 create a file in your own runtime directory to load that one.  The name of
 151 that file could be: >
 152
 153         ~/.vim/lang/menu_<v:lang>.vim
 154
 155 Check the 'runtimepath' option for directories which are searched.  In that
 156 file put a command to load the menu file with the other name: >
 157
 158         runtime lang/menu_<other_lang>.vim
 159
 160
 161 TRANSLATING MENUS
 162
 163 If you want to do your own translations, you can use the |:menutrans| command,
 164 explained below.  It is recommended to put the translations for one language
 165 in a Vim script.  For a language that has no translation yet, please consider
 166 becoming the maintainer and make your translations available to all Vim users.
 167 Send an e-mail to the Vim maintainer <maintainer@vim.org>.
 168
 169                                         *:menut* *:menutrans* *:menutranslate*
 170 :menut[ranslate] clear
 171                         Clear all menu translations.
 172
 173 :menut[ranslate] {english} {mylang}
 174                         Translate menu name {english} to {mylang}.  All
 175                         special characters like "&" and "<Tab>" need to be
 176                         included.  Spaces and dots need to be escaped with a
 177                         backslash, just like in other |:menu| commands.
 178
 179 See the $VIMRUNTIME/lang directory for examples.
 180
 181 To try out your translations you first have to remove all menus.  This is how
 182 you can do it without restarting Vim: >
 183         :source $VIMRUNTIME/delmenu.vim
 184         :source <your-new-menu-file>
 185         :source $VIMRUNTIME/menu.vim
 186
 187 Each part of a menu path is translated separately.  The result is that when
 188 "Help" is translated to "Hilfe" and "Overview" to "Überblick" then
 189 "Help.Overview" will be translated to "Hilfe.Überblick".
 190
 191 ==============================================================================
 192 3. Scripts                                              *multilang-scripts*
 193
 194 In Vim scripts you can use the |v:lang| variable to get the current language
 195 (locale).  The default value is "C" or comes from the $LANG environment
 196 variable.
 197
 198 The following example shows how this variable is used in a simple way, to make
 199 a message adapt to language preferences of the user, >
 200
 201         :if v:lang =~ "de_DE"
 202         :  echo "Guten Morgen"
 203         :else
 204         :  echo "Good morning"
 205         :endif
 206 <
 207
 208  vim:tw=78:sw=4:ts=8:ft=help:norl: