Mercurial > vim
annotate runtime/doc/usr_45.txt @ 20856:83cfa1ef1bf2
Update runtime files
Commit: https://github.com/vim/vim/commit/65e0d77a66b7e50beb562ad554ace46c32ef8f0f
Author: Bram Moolenaar <Bram@vim.org>
Date: Sun Jun 14 17:29:55 2020 +0200
Update runtime files
| author | Bram Moolenaar <Bram@vim.org> |
|---|---|
| date | Sun, 14 Jun 2020 17:45:04 +0200 |
| parents | af69c9335223 |
| children | 82244cfc4694 |
| rev | line source |
|---|---|
| 20856 | 1 *usr_45.txt* For Vim version 8.2. Last change: 2020 Jun 11 |
| 7 | 2 |
| 3 VIM USER MANUAL - by Bram Moolenaar | |
| 4 | |
| 20856 | 5 Select your language (locale) |
| 7 | 6 |
| 7 | |
| 8 The messages in Vim can be given in several languages. This chapter explains | |
| 9 how to change which one is used. Also, the different ways to work with files | |
| 10 in various languages is explained. | |
| 11 | |
| 12 |45.1| Language for Messages | |
| 13 |45.2| Language for Menus | |
| 14 |45.3| Using another encoding | |
| 15 |45.4| Editing files with a different encoding | |
| 16 |45.5| Entering language text | |
| 17 | |
| 20856 | 18 Next chapter: |usr_46.txt| Write plugins using Vim9 script |
| 7 | 19 Previous chapter: |usr_44.txt| Your own syntax highlighted |
| 20 Table of contents: |usr_toc.txt| | |
| 21 | |
| 22 ============================================================================== | |
| 23 *45.1* Language for Messages | |
| 24 | |
| 25 When you start Vim, it checks the environment to find out what language you | |
| 26 are using. Mostly this should work fine, and you get the messages in your | |
| 27 language (if they are available). To see what the current language is, use | |
| 28 this command: > | |
| 29 | |
| 30 :language | |
| 31 | |
| 32 If it replies with "C", this means the default is being used, which is | |
| 33 English. | |
| 34 | |
| 35 Note: | |
| 36 Using different languages only works when Vim was compiled to handle | |
| 37 it. To find out if it works, use the ":version" command and check the | |
| 38 output for "+gettext" and "+multi_lang". If they are there, you are | |
| 39 OK. If you see "-gettext" or "-multi_lang" you will have to find | |
| 40 another Vim. | |
| 41 | |
| 42 What if you would like your messages in a different language? There are | |
| 43 several ways. Which one you should use depends on the capabilities of your | |
| 44 system. | |
| 45 The first way is to set the environment to the desired language before | |
| 46 starting Vim. Example for Unix: > | |
| 47 | |
| 48 env LANG=de_DE.ISO_8859-1 vim | |
| 49 | |
| 50 This only works if the language is available on your system. The advantage is | |
| 51 that all the GUI messages and things in libraries will use the right language | |
| 52 as well. A disadvantage is that you must do this before starting Vim. If you | |
| 53 want to change language while Vim is running, you can use the second method: > | |
| 54 | |
| 55 :language fr_FR.ISO_8859-1 | |
| 56 | |
| 57 This way you can try out several names for your language. You will get an | |
| 58 error message when it's not supported on your system. You don't get an error | |
| 59 when translated messages are not available. Vim will silently fall back to | |
| 60 using English. | |
| 61 To find out which languages are supported on your system, find the | |
| 62 directory where they are listed. On my system it is "/usr/share/locale". On | |
| 63 some systems it's in "/usr/lib/locale". The manual page for "setlocale" | |
| 64 should give you a hint where it is found on your system. | |
| 65 Be careful to type the name exactly as it should be. Upper and lowercase | |
| 66 matter, and the '-' and '_' characters are easily confused. | |
| 67 | |
| 68 You can also set the language separately for messages, edited text and the | |
| 69 time format. See |:language|. | |
| 70 | |
| 71 | |
| 72 DO-IT-YOURSELF MESSAGE TRANSLATION | |
| 73 | |
| 74 If translated messages are not available for your language, you could write | |
| 75 them yourself. To do this, get the source code for Vim and the GNU gettext | |
| 76 package. After unpacking the sources, instructions can be found in the | |
| 77 directory src/po/README.txt. | |
| 78 It's not too difficult to do the translation. You don't need to be a | |
| 79 programmer. You must know both English and the language you are translating | |
| 80 to, of course. | |
| 81 When you are satisfied with the translation, consider making it available | |
| 82 to others. Upload it at vim-online (http://vim.sf.net) or e-mail it to | |
| 83 the Vim maintainer <maintainer@vim.org>. Or both. | |
| 84 | |
| 85 ============================================================================== | |
| 86 *45.2* Language for Menus | |
| 87 | |
| 88 The default menus are in English. To be able to use your local language, they | |
| 89 must be translated. Normally this is automatically done for you if the | |
| 90 environment is set for your language, just like with messages. You don't need | |
| 91 to do anything extra for this. But it only works if translations for the | |
| 92 language are available. | |
| 93 Suppose you are in Germany, with the language set to German, but prefer to | |
| 94 use "File" instead of "Datei". You can switch back to using the English menus | |
| 95 this way: > | |
| 96 | |
| 97 :set langmenu=none | |
| 98 | |
| 99 It is also possible to specify a language: > | |
| 100 | |
| 101 :set langmenu=nl_NL.ISO_8859-1 | |
| 102 | |
| 103 Like above, differences between "-" and "_" matter. However, upper/lowercase | |
| 104 differences are ignored here. | |
| 105 The 'langmenu' option must be set before the menus are loaded. Once the | |
| 106 menus have been defined changing 'langmenu' has no direct effect. Therefore, | |
| 107 put the command to set 'langmenu' in your vimrc file. | |
| 108 If you really want to switch menu language while running Vim, you can do it | |
| 109 this way: > | |
| 110 | |
| 111 :source $VIMRUNTIME/delmenu.vim | |
| 112 :set langmenu=de_DE.ISO_8859-1 | |
| 113 :source $VIMRUNTIME/menu.vim | |
| 114 | |
| 115 There is one drawback: All menus that you defined yourself will be gone. You | |
| 116 will need to redefine them as well. | |
| 117 | |
| 118 | |
| 119 DO-IT-YOURSELF MENU TRANSLATION | |
| 120 | |
| 121 To see which menu translations are available, look in this directory: | |
| 122 | |
| 123 $VIMRUNTIME/lang ~ | |
| 124 | |
| 125 The files are called menu_{language}.vim. If you don't see the language you | |
| 126 want to use, you can do your own translations. The simplest way to do this is | |
| 127 by copying one of the existing language files, and change it. | |
| 128 First find out the name of your language with the ":language" command. Use | |
| 129 this name, but with all letters made lowercase. Then copy the file to your | |
| 130 own runtime directory, as found early in 'runtimepath'. For example, for Unix | |
| 131 you would do: > | |
| 132 | |
| 133 :!cp $VIMRUNTIME/lang/menu_ko_kr.euckr.vim ~/.vim/lang/menu_nl_be.iso_8859-1.vim | |
| 134 | |
| 135 You will find hints for the translation in "$VIMRUNTIME/lang/README.txt". | |
| 136 | |
| 137 ============================================================================== | |
| 138 *45.3* Using another encoding | |
| 139 | |
| 140 Vim guesses that the files you are going to edit are encoded for your | |
| 141 language. For many European languages this is "latin1". Then each byte is | |
| 142 one character. That means there are 256 different characters possible. For | |
| 143 Asian languages this is not sufficient. These mostly use a double-byte | |
| 144 encoding, providing for over ten thousand possible characters. This still | |
| 145 isn't enough when a text is to contain several different languages. This is | |
| 146 where Unicode comes in. It was designed to include all characters used in | |
| 147 commonly used languages. This is the "Super encoding that replaces all | |
| 148 others". But it isn't used that much yet. | |
| 149 Fortunately, Vim supports these three kinds of encodings. And, with some | |
| 150 restrictions, you can use them even when your environment uses another | |
| 151 language than the text. | |
| 152 Nevertheless, when you only edit files that are in the encoding of your | |
| 153 language, the default should work fine and you don't need to do anything. The | |
| 154 following is only relevant when you want to edit different languages. | |
| 155 | |
| 156 | |
| 157 USING UNICODE IN THE GUI | |
| 158 | |
| 159 The nice thing about Unicode is that other encodings can be converted to it | |
| 160 and back without losing information. When you make Vim use Unicode | |
| 161 internally, you will be able to edit files in any encoding. | |
| 162 Unfortunately, the number of systems supporting Unicode is still limited. | |
| 163 Thus it's unlikely that your language uses it. You need to tell Vim you want | |
| 164 to use Unicode, and how to handle interfacing with the rest of the system. | |
| 165 Let's start with the GUI version of Vim, which is able to display Unicode | |
| 166 characters. This should work: > | |
| 167 | |
| 168 :set encoding=utf-8 | |
| 169 :set guifont=-misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1 | |
| 170 | |
| 171 The 'encoding' option tells Vim the encoding of the characters that you use. | |
| 172 This applies to the text in buffers (files you are editing), registers, Vim | |
| 173 script files, etc. You can regard 'encoding' as the setting for the internals | |
| 174 of Vim. | |
| 175 This example assumes you have this font on your system. The name in the | |
| 176 example is for the X Window System. This font is in a package that is used to | |
| 177 enhance xterm with Unicode support. If you don't have this font, you might | |
| 178 find it here: | |
| 179 | |
| 180 http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz ~ | |
| 181 | |
| 182 For MS-Windows, some fonts have a limited number of Unicode characters. Try | |
| 183 using the "Courier New" font. You can use the Edit/Select Font... menu to | |
| 184 select and try out the fonts available. Only fixed-width fonts can be used | |
| 185 though. Example: > | |
| 186 | |
| 187 :set guifont=courier_new:h12 | |
| 188 | |
| 189 If it doesn't work well, try getting a fontpack. If Microsoft didn't move it, | |
| 190 you can find it here: | |
| 191 | |
| 1618 | 192 http://www.microsoft.com/typography/fonts/default.aspx ~ |
| 7 | 193 |
| 194 Now you have told Vim to use Unicode internally and display text with a | |
| 195 Unicode font. Typed characters still arrive in the encoding of your original | |
| 196 language. This requires converting them to Unicode. Tell Vim the language | |
| 197 from which to convert with the 'termencoding' option. You can do it like | |
| 198 this: > | |
| 199 | |
| 200 :let &termencoding = &encoding | |
| 201 :set encoding=utf-8 | |
| 202 | |
| 203 This assigns the old value of 'encoding' to 'termencoding' before setting | |
| 204 'encoding' to utf-8. You will have to try out if this really works for your | |
| 205 setup. It should work especially well when using an input method for an Asian | |
| 206 language, and you want to edit Unicode text. | |
| 207 | |
| 208 | |
| 209 USING UNICODE IN A UNICODE TERMINAL | |
| 210 | |
| 211 There are terminals that support Unicode directly. The standard xterm that | |
| 212 comes with XFree86 is one of them. Let's use that as an example. | |
| 213 First of all, the xterm must have been compiled with Unicode support. See | |
| 214 |UTF8-xterm| how to check that and how to compile it when needed. | |
| 215 Start the xterm with the "-u8" argument. You might also need so specify a | |
| 216 font. Example: > | |
| 217 | |
| 218 xterm -u8 -fn -misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1 | |
| 219 | |
| 220 Now you can run Vim inside this terminal. Set 'encoding' to "utf-8" as | |
| 221 before. That's all. | |
| 222 | |
| 223 | |
| 224 USING UNICODE IN AN ORDINARY TERMINAL | |
| 225 | |
| 226 Suppose you want to work with Unicode files, but don't have a terminal with | |
| 227 Unicode support. You can do this with Vim, although characters that are not | |
| 228 supported by the terminal will not be displayed. The layout of the text | |
| 229 will be preserved. > | |
| 230 | |
| 231 :let &termencoding = &encoding | |
| 232 :set encoding=utf-8 | |
| 233 | |
| 234 This is the same as what was used for the GUI. But it works differently: Vim | |
| 235 will convert the displayed text before sending it to the terminal. That | |
| 236 avoids that the display is messed up with strange characters. | |
| 237 For this to work the conversion between 'termencoding' and 'encoding' must | |
| 238 be possible. Vim will convert from latin1 to Unicode, thus that always works. | |
| 239 For other conversions the |+iconv| feature is required. | |
| 240 Try editing a file with Unicode characters in it. You will notice that Vim | |
| 241 will put a question mark (or underscore or some other character) in places | |
| 242 where a character should be that the terminal can't display. Move the cursor | |
| 243 to a question mark and use this command: > | |
| 244 | |
| 245 ga | |
| 246 | |
| 247 Vim will display a line with the code of the character. This gives you a hint | |
| 248 about what character it is. You can look it up in a Unicode table. You could | |
| 249 actually view a file that way, if you have lots of time at hand. | |
| 250 | |
| 251 Note: | |
| 252 Since 'encoding' is used for all text inside Vim, changing it makes | |
| 253 all non-ASCII text invalid. You will notice this when using registers | |
| 254 and the 'viminfo' file (e.g., a remembered search pattern). It's | |
| 255 recommended to set 'encoding' in your vimrc file, and leave it alone. | |
| 256 | |
| 257 ============================================================================== | |
| 258 *45.4* Editing files with a different encoding | |
| 259 | |
| 260 Suppose you have setup Vim to use Unicode, and you want to edit a file that is | |
| 261 in 16-bit Unicode. Sounds simple, right? Well, Vim actually uses utf-8 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
262 encoding internally, thus the 16-bit encoding must be converted, since there |
| 7 | 263 is a difference between the character set (Unicode) and the encoding (utf-8 or |
| 264 16-bit). | |
| 265 Vim will try to detect what kind of file you are editing. It uses the | |
| 266 encoding names in the 'fileencodings' option. When using Unicode, the default | |
| 267 value is: "ucs-bom,utf-8,latin1". This means that Vim checks the file to see | |
| 268 if it's one of these encodings: | |
| 269 | |
| 270 ucs-bom File must start with a Byte Order Mark (BOM). This | |
| 271 allows detection of 16-bit, 32-bit and utf-8 Unicode | |
| 272 encodings. | |
| 273 utf-8 utf-8 Unicode. This is rejected when a sequence of | |
| 274 bytes is illegal in utf-8. | |
| 275 latin1 The good old 8-bit encoding. Always works. | |
| 276 | |
| 277 When you start editing that 16-bit Unicode file, and it has a BOM, Vim will | |
| 278 detect this and convert the file to utf-8 when reading it. The 'fileencoding' | |
| 279 option (without s at the end) is set to the detected value. In this case it | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
280 is "utf-16le". That means it's Unicode, 16-bit and little-endian. This |
| 7 | 281 file format is common on MS-Windows (e.g., for registry files). |
| 282 When writing the file, Vim will compare 'fileencoding' with 'encoding'. If | |
| 283 they are different, the text will be converted. | |
| 284 An empty value for 'fileencoding' means that no conversion is to be done. | |
| 285 Thus the text is assumed to be encoded with 'encoding'. | |
| 286 | |
| 287 If the default 'fileencodings' value is not good for you, set it to the | |
| 288 encodings you want Vim to try. Only when a value is found to be invalid will | |
| 289 the next one be used. Putting "latin1" first doesn't work, because it is | |
| 290 never illegal. An example, to fall back to Japanese when the file doesn't | |
| 291 have a BOM and isn't utf-8: > | |
| 292 | |
| 293 :set fileencodings=ucs-bom,utf-8,sjis | |
| 294 | |
| 295 See |encoding-values| for suggested values. Other values may work as well. | |
| 296 This depends on the conversion available. | |
| 297 | |
| 298 | |
| 299 FORCING AN ENCODING | |
| 300 | |
| 301 If the automatic detection doesn't work you must tell Vim what encoding the | |
| 302 file is. Example: > | |
| 303 | |
| 304 :edit ++enc=koi8-r russian.txt | |
| 305 | |
| 306 The "++enc" part specifies the name of the encoding to be used for this file | |
| 307 only. Vim will convert the file from the specified encoding, Russian in this | |
| 308 example, to 'encoding'. 'fileencoding' will also be set to the specified | |
| 309 encoding, so that the reverse conversion can be done when writing the file. | |
| 310 The same argument can be used when writing the file. This way you can | |
| 311 actually use Vim to convert a file. Example: > | |
| 312 | |
| 313 :write ++enc=utf-8 russian.txt | |
| 314 < | |
| 315 Note: | |
| 316 Conversion may result in lost characters. Conversion from an encoding | |
| 317 to Unicode and back is mostly free of this problem, unless there are | |
| 318 illegal characters. Conversion from Unicode to other encodings often | |
| 319 loses information when there was more than one language in the file. | |
| 320 | |
| 321 ============================================================================== | |
| 322 *45.5* Entering language text | |
| 323 | |
| 324 Computer keyboards don't have much more than a hundred keys. Some languages | |
|
5362
ab1508486b12
Update runtime files. Add support for J.
Bram Moolenaar <bram@vim.org>
parents:
5294
diff
changeset
|
325 have thousands of characters, Unicode has over hundred thousand. So how do |
|
ab1508486b12
Update runtime files. Add support for J.
Bram Moolenaar <bram@vim.org>
parents:
5294
diff
changeset
|
326 you type these characters? |
| 7 | 327 First of all, when you don't use too many of the special characters, you |
| 328 can use digraphs. This was already explained in |24.9|. | |
| 329 When you use a language that uses many more characters than keys on your | |
| 330 keyboard, you will want to use an Input Method (IM). This requires learning | |
| 331 the translation from typed keys to resulting character. When you need an IM | |
| 332 you probably already have one on your system. It should work with Vim like | |
| 333 with other programs. For details see |mbyte-XIM| for the X Window system and | |
| 334 |mbyte-IME| for MS-Windows. | |
| 335 | |
| 336 | |
| 337 KEYMAPS | |
| 338 | |
| 339 For some languages the character set is different from latin, but uses a | |
| 340 similar number of characters. It's possible to map keys to characters. Vim | |
| 341 uses keymaps for this. | |
| 342 Suppose you want to type Hebrew. You can load the keymap like this: > | |
| 343 | |
| 344 :set keymap=hebrew | |
| 345 | |
| 346 Vim will try to find a keymap file for you. This depends on the value of | |
| 347 'encoding'. If no matching file was found, you will get an error message. | |
| 348 | |
| 349 Now you can type Hebrew in Insert mode. In Normal mode, and when typing a ":" | |
| 350 command, Vim automatically switches to English. You can use this command to | |
| 351 switch between Hebrew and English: > | |
| 352 | |
| 353 CTRL-^ | |
| 354 | |
| 355 This only works in Insert mode and Command-line mode. In Normal mode it does | |
| 356 something completely different (jumps to alternate file). | |
| 357 The usage of the keymap is indicated in the mode message, if you have the | |
| 358 'showmode' option set. In the GUI Vim will indicate the usage of keymaps with | |
| 359 a different cursor color. | |
| 360 You can also change the usage of the keymap with the 'iminsert' and | |
| 361 'imsearch' options. | |
| 362 | |
| 363 To see the list of mappings, use this command: > | |
| 364 | |
| 365 :lmap | |
| 366 | |
| 367 To find out which keymap files are available, in the GUI you can use the | |
| 368 Edit/Keymap menu. Otherwise you can use this command: > | |
| 369 | |
| 370 :echo globpath(&rtp, "keymap/*.vim") | |
| 371 | |
| 372 | |
| 373 DO-IT-YOURSELF KEYMAPS | |
| 374 | |
| 375 You can create your own keymap file. It's not very difficult. Start with | |
| 376 a keymap file that is similar to the language you want to use. Copy it to the | |
| 377 "keymap" directory in your runtime directory. For example, for Unix, you | |
| 378 would use the directory "~/.vim/keymap". | |
| 379 The name of the keymap file must look like this: | |
| 380 | |
| 381 keymap/{name}.vim ~ | |
| 382 or | |
| 383 keymap/{name}_{encoding}.vim ~ | |
| 384 | |
| 385 {name} is the name of the keymap. Chose a name that is obvious, but different | |
| 386 from existing keymaps (unless you want to replace an existing keymap file). | |
| 387 {name} cannot contain an underscore. Optionally, add the encoding used after | |
| 388 an underscore. Examples: | |
| 389 | |
| 390 keymap/hebrew.vim ~ | |
| 391 keymap/hebrew_utf-8.vim ~ | |
| 392 | |
| 393 The contents of the file should be self-explanatory. Look at a few of the | |
| 394 keymaps that are distributed with Vim. For the details, see |mbyte-keymap|. | |
| 395 | |
| 396 | |
| 397 LAST RESORT | |
| 398 | |
| 399 If all other methods fail, you can enter any character with CTRL-V: | |
| 400 | |
| 401 encoding type range ~ | |
| 402 8-bit CTRL-V 123 decimal 0-255 | |
| 403 8-bit CTRL-V x a1 hexadecimal 00-ff | |
| 404 16-bit CTRL-V u 013b hexadecimal 0000-ffff | |
| 405 31-bit CTRL-V U 001303a4 hexadecimal 00000000-7fffffff | |
| 406 | |
| 407 Don't type the spaces. See |i_CTRL-V_digit| for the details. | |
| 408 | |
| 409 ============================================================================== | |
| 410 | |
| 20856 | 411 Next chapter: |usr_46.txt| Write plugins using Vim9 script |
| 7 | 412 |
| 14519 | 413 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |