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