| *usr_45.txt* For Vim version 7.2. Last change: 2008 Apr 30 |
| |
| VIM USER MANUAL - by Bram Moolenaar |
| |
| Select your language |
| |
| |
| The messages in Vim can be given in several languages. This chapter explains |
| how to change which one is used. Also, the different ways to work with files |
| in various languages is explained. |
| |
| |45.1| Language for Messages |
| |45.2| Language for Menus |
| |45.3| Using another encoding |
| |45.4| Editing files with a different encoding |
| |45.5| Entering language text |
| |
| Next chapter: |usr_90.txt| Installing Vim |
| Previous chapter: |usr_44.txt| Your own syntax highlighted |
| Table of contents: |usr_toc.txt| |
| |
| ============================================================================== |
| *45.1* Language for Messages |
| |
| When you start Vim, it checks the environment to find out what language you |
| are using. Mostly this should work fine, and you get the messages in your |
| language (if they are available). To see what the current language is, use |
| this command: > |
| |
| :language |
| |
| If it replies with "C", this means the default is being used, which is |
| English. |
| |
| Note: |
| Using different languages only works when Vim was compiled to handle |
| it. To find out if it works, use the ":version" command and check the |
| output for "+gettext" and "+multi_lang". If they are there, you are |
| OK. If you see "-gettext" or "-multi_lang" you will have to find |
| another Vim. |
| |
| What if you would like your messages in a different language? There are |
| several ways. Which one you should use depends on the capabilities of your |
| system. |
| The first way is to set the environment to the desired language before |
| starting Vim. Example for Unix: > |
| |
| env LANG=de_DE.ISO_8859-1 vim |
| |
| This only works if the language is available on your system. The advantage is |
| that all the GUI messages and things in libraries will use the right language |
| as well. A disadvantage is that you must do this before starting Vim. If you |
| want to change language while Vim is running, you can use the second method: > |
| |
| :language fr_FR.ISO_8859-1 |
| |
| This way you can try out several names for your language. You will get an |
| error message when it's not supported on your system. You don't get an error |
| when translated messages are not available. Vim will silently fall back to |
| using English. |
| To find out which languages are supported on your system, find the |
| directory where they are listed. On my system it is "/usr/share/locale". On |
| some systems it's in "/usr/lib/locale". The manual page for "setlocale" |
| should give you a hint where it is found on your system. |
| Be careful to type the name exactly as it should be. Upper and lowercase |
| matter, and the '-' and '_' characters are easily confused. |
| |
| You can also set the language separately for messages, edited text and the |
| time format. See |:language|. |
| |
| |
| DO-IT-YOURSELF MESSAGE TRANSLATION |
| |
| If translated messages are not available for your language, you could write |
| them yourself. To do this, get the source code for Vim and the GNU gettext |
| package. After unpacking the sources, instructions can be found in the |
| directory src/po/README.txt. |
| It's not too difficult to do the translation. You don't need to be a |
| programmer. You must know both English and the language you are translating |
| to, of course. |
| When you are satisfied with the translation, consider making it available |
| to others. Upload it at vim-online (http://vim.sf.net) or e-mail it to |
| the Vim maintainer <maintainer@vim.org>. Or both. |
| |
| ============================================================================== |
| *45.2* Language for Menus |
| |
| The default menus are in English. To be able to use your local language, they |
| must be translated. Normally this is automatically done for you if the |
| environment is set for your language, just like with messages. You don't need |
| to do anything extra for this. But it only works if translations for the |
| language are available. |
| Suppose you are in Germany, with the language set to German, but prefer to |
| use "File" instead of "Datei". You can switch back to using the English menus |
| this way: > |
| |
| :set langmenu=none |
| |
| It is also possible to specify a language: > |
| |
| :set langmenu=nl_NL.ISO_8859-1 |
| |
| Like above, differences between "-" and "_" matter. However, upper/lowercase |
| differences are ignored here. |
| The 'langmenu' option must be set before the menus are loaded. Once the |
| menus have been defined changing 'langmenu' has no direct effect. Therefore, |
| put the command to set 'langmenu' in your vimrc file. |
| If you really want to switch menu language while running Vim, you can do it |
| this way: > |
| |
| :source $VIMRUNTIME/delmenu.vim |
| :set langmenu=de_DE.ISO_8859-1 |
| :source $VIMRUNTIME/menu.vim |
| |
| There is one drawback: All menus that you defined yourself will be gone. You |
| will need to redefine them as well. |
| |
| |
| DO-IT-YOURSELF MENU TRANSLATION |
| |
| To see which menu translations are available, look in this directory: |
| |
| $VIMRUNTIME/lang ~ |
| |
| The files are called menu_{language}.vim. If you don't see the language you |
| want to use, you can do your own translations. The simplest way to do this is |
| by copying one of the existing language files, and change it. |
| First find out the name of your language with the ":language" command. Use |
| this name, but with all letters made lowercase. Then copy the file to your |
| own runtime directory, as found early in 'runtimepath'. For example, for Unix |
| you would do: > |
| |
| :!cp $VIMRUNTIME/lang/menu_ko_kr.euckr.vim ~/.vim/lang/menu_nl_be.iso_8859-1.vim |
| |
| You will find hints for the translation in "$VIMRUNTIME/lang/README.txt". |
| |
| ============================================================================== |
| *45.3* Using another encoding |
| |
| Vim guesses that the files you are going to edit are encoded for your |
| language. For many European languages this is "latin1". Then each byte is |
| one character. That means there are 256 different characters possible. For |
| Asian languages this is not sufficient. These mostly use a double-byte |
| encoding, providing for over ten thousand possible characters. This still |
| isn't enough when a text is to contain several different languages. This is |
| where Unicode comes in. It was designed to include all characters used in |
| commonly used languages. This is the "Super encoding that replaces all |
| others". But it isn't used that much yet. |
| Fortunately, Vim supports these three kinds of encodings. And, with some |
| restrictions, you can use them even when your environment uses another |
| language than the text. |
| Nevertheless, when you only edit files that are in the encoding of your |
| language, the default should work fine and you don't need to do anything. The |
| following is only relevant when you want to edit different languages. |
| |
| Note: |
| Using different encodings only works when Vim was compiled to handle |
| it. To find out if it works, use the ":version" command and check the |
| output for "+multi_byte". If it's there, you are OK. If you see |
| "-multi_byte" you will have to find another Vim. |
| |
| |
| USING UNICODE IN THE GUI |
| |
| The nice thing about Unicode is that other encodings can be converted to it |
| and back without losing information. When you make Vim use Unicode |
| internally, you will be able to edit files in any encoding. |
| Unfortunately, the number of systems supporting Unicode is still limited. |
| Thus it's unlikely that your language uses it. You need to tell Vim you want |
| to use Unicode, and how to handle interfacing with the rest of the system. |
| Let's start with the GUI version of Vim, which is able to display Unicode |
| characters. This should work: > |
| |
| :set encoding=utf-8 |
| :set guifont=-misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1 |
| |
| The 'encoding' option tells Vim the encoding of the characters that you use. |
| This applies to the text in buffers (files you are editing), registers, Vim |
| script files, etc. You can regard 'encoding' as the setting for the internals |
| of Vim. |
| This example assumes you have this font on your system. The name in the |
| example is for the X Window System. This font is in a package that is used to |
| enhance xterm with Unicode support. If you don't have this font, you might |
| find it here: |
| |
| http://www.cl.cam.ac.uk/~mgk25/download/ucs-fonts.tar.gz ~ |
| |
| For MS-Windows, some fonts have a limited number of Unicode characters. Try |
| using the "Courier New" font. You can use the Edit/Select Font... menu to |
| select and try out the fonts available. Only fixed-width fonts can be used |
| though. Example: > |
| |
| :set guifont=courier_new:h12 |
| |
| If it doesn't work well, try getting a fontpack. If Microsoft didn't move it, |
| you can find it here: |
| |
| http://www.microsoft.com/typography/fonts/default.aspx ~ |
| |
| Now you have told Vim to use Unicode internally and display text with a |
| Unicode font. Typed characters still arrive in the encoding of your original |
| language. This requires converting them to Unicode. Tell Vim the language |
| from which to convert with the 'termencoding' option. You can do it like |
| this: > |
| |
| :let &termencoding = &encoding |
| :set encoding=utf-8 |
| |
| This assigns the old value of 'encoding' to 'termencoding' before setting |
| 'encoding' to utf-8. You will have to try out if this really works for your |
| setup. It should work especially well when using an input method for an Asian |
| language, and you want to edit Unicode text. |
| |
| |
| USING UNICODE IN A UNICODE TERMINAL |
| |
| There are terminals that support Unicode directly. The standard xterm that |
| comes with XFree86 is one of them. Let's use that as an example. |
| First of all, the xterm must have been compiled with Unicode support. See |
| |UTF8-xterm| how to check that and how to compile it when needed. |
| Start the xterm with the "-u8" argument. You might also need so specify a |
| font. Example: > |
| |
| xterm -u8 -fn -misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1 |
| |
| Now you can run Vim inside this terminal. Set 'encoding' to "utf-8" as |
| before. That's all. |
| |
| |
| USING UNICODE IN AN ORDINARY TERMINAL |
| |
| Suppose you want to work with Unicode files, but don't have a terminal with |
| Unicode support. You can do this with Vim, although characters that are not |
| supported by the terminal will not be displayed. The layout of the text |
| will be preserved. > |
| |
| :let &termencoding = &encoding |
| :set encoding=utf-8 |
| |
| This is the same as what was used for the GUI. But it works differently: Vim |
| will convert the displayed text before sending it to the terminal. That |
| avoids that the display is messed up with strange characters. |
| For this to work the conversion between 'termencoding' and 'encoding' must |
| be possible. Vim will convert from latin1 to Unicode, thus that always works. |
| For other conversions the |+iconv| feature is required. |
| Try editing a file with Unicode characters in it. You will notice that Vim |
| will put a question mark (or underscore or some other character) in places |
| where a character should be that the terminal can't display. Move the cursor |
| to a question mark and use this command: > |
| |
| ga |
| |
| Vim will display a line with the code of the character. This gives you a hint |
| about what character it is. You can look it up in a Unicode table. You could |
| actually view a file that way, if you have lots of time at hand. |
| |
| Note: |
| Since 'encoding' is used for all text inside Vim, changing it makes |
| all non-ASCII text invalid. You will notice this when using registers |
| and the 'viminfo' file (e.g., a remembered search pattern). It's |
| recommended to set 'encoding' in your vimrc file, and leave it alone. |
| |
| ============================================================================== |
| *45.4* Editing files with a different encoding |
| |
| Suppose you have setup Vim to use Unicode, and you want to edit a file that is |
| in 16-bit Unicode. Sounds simple, right? Well, Vim actually uses utf-8 |
| encoding internally, thus the 16-bit encoding must be converted. Thus there |
| is a difference between the character set (Unicode) and the encoding (utf-8 or |
| 16-bit). |
| Vim will try to detect what kind of file you are editing. It uses the |
| encoding names in the 'fileencodings' option. When using Unicode, the default |
| value is: "ucs-bom,utf-8,latin1". This means that Vim checks the file to see |
| if it's one of these encodings: |
| |
| ucs-bom File must start with a Byte Order Mark (BOM). This |
| allows detection of 16-bit, 32-bit and utf-8 Unicode |
| encodings. |
| utf-8 utf-8 Unicode. This is rejected when a sequence of |
| bytes is illegal in utf-8. |
| latin1 The good old 8-bit encoding. Always works. |
| |
| When you start editing that 16-bit Unicode file, and it has a BOM, Vim will |
| detect this and convert the file to utf-8 when reading it. The 'fileencoding' |
| option (without s at the end) is set to the detected value. In this case it |
| is "ucs-2le". That means it's Unicode, two bytes and little-endian. This |
| file format is common on MS-Windows (e.g., for registry files). |
| When writing the file, Vim will compare 'fileencoding' with 'encoding'. If |
| they are different, the text will be converted. |
| An empty value for 'fileencoding' means that no conversion is to be done. |
| Thus the text is assumed to be encoded with 'encoding'. |
| |
| If the default 'fileencodings' value is not good for you, set it to the |
| encodings you want Vim to try. Only when a value is found to be invalid will |
| the next one be used. Putting "latin1" first doesn't work, because it is |
| never illegal. An example, to fall back to Japanese when the file doesn't |
| have a BOM and isn't utf-8: > |
| |
| :set fileencodings=ucs-bom,utf-8,sjis |
| |
| See |encoding-values| for suggested values. Other values may work as well. |
| This depends on the conversion available. |
| |
| |
| FORCING AN ENCODING |
| |
| If the automatic detection doesn't work you must tell Vim what encoding the |
| file is. Example: > |
| |
| :edit ++enc=koi8-r russian.txt |
| |
| The "++enc" part specifies the name of the encoding to be used for this file |
| only. Vim will convert the file from the specified encoding, Russian in this |
| example, to 'encoding'. 'fileencoding' will also be set to the specified |
| encoding, so that the reverse conversion can be done when writing the file. |
| The same argument can be used when writing the file. This way you can |
| actually use Vim to convert a file. Example: > |
| |
| :write ++enc=utf-8 russian.txt |
| < |
| Note: |
| Conversion may result in lost characters. Conversion from an encoding |
| to Unicode and back is mostly free of this problem, unless there are |
| illegal characters. Conversion from Unicode to other encodings often |
| loses information when there was more than one language in the file. |
| |
| ============================================================================== |
| *45.5* Entering language text |
| |
| Computer keyboards don't have much more than a hundred keys. Some languages |
| have thousands of characters, Unicode has ten thousands. So how do you type |
| these characters? |
| First of all, when you don't use too many of the special characters, you |
| can use digraphs. This was already explained in |24.9|. |
| When you use a language that uses many more characters than keys on your |
| keyboard, you will want to use an Input Method (IM). This requires learning |
| the translation from typed keys to resulting character. When you need an IM |
| you probably already have one on your system. It should work with Vim like |
| with other programs. For details see |mbyte-XIM| for the X Window system and |
| |mbyte-IME| for MS-Windows. |
| |
| |
| KEYMAPS |
| |
| For some languages the character set is different from latin, but uses a |
| similar number of characters. It's possible to map keys to characters. Vim |
| uses keymaps for this. |
| Suppose you want to type Hebrew. You can load the keymap like this: > |
| |
| :set keymap=hebrew |
| |
| Vim will try to find a keymap file for you. This depends on the value of |
| 'encoding'. If no matching file was found, you will get an error message. |
| |
| Now you can type Hebrew in Insert mode. In Normal mode, and when typing a ":" |
| command, Vim automatically switches to English. You can use this command to |
| switch between Hebrew and English: > |
| |
| CTRL-^ |
| |
| This only works in Insert mode and Command-line mode. In Normal mode it does |
| something completely different (jumps to alternate file). |
| The usage of the keymap is indicated in the mode message, if you have the |
| 'showmode' option set. In the GUI Vim will indicate the usage of keymaps with |
| a different cursor color. |
| You can also change the usage of the keymap with the 'iminsert' and |
| 'imsearch' options. |
| |
| To see the list of mappings, use this command: > |
| |
| :lmap |
| |
| To find out which keymap files are available, in the GUI you can use the |
| Edit/Keymap menu. Otherwise you can use this command: > |
| |
| :echo globpath(&rtp, "keymap/*.vim") |
| |
| |
| DO-IT-YOURSELF KEYMAPS |
| |
| You can create your own keymap file. It's not very difficult. Start with |
| a keymap file that is similar to the language you want to use. Copy it to the |
| "keymap" directory in your runtime directory. For example, for Unix, you |
| would use the directory "~/.vim/keymap". |
| The name of the keymap file must look like this: |
| |
| keymap/{name}.vim ~ |
| or |
| keymap/{name}_{encoding}.vim ~ |
| |
| {name} is the name of the keymap. Chose a name that is obvious, but different |
| from existing keymaps (unless you want to replace an existing keymap file). |
| {name} cannot contain an underscore. Optionally, add the encoding used after |
| an underscore. Examples: |
| |
| keymap/hebrew.vim ~ |
| keymap/hebrew_utf-8.vim ~ |
| |
| The contents of the file should be self-explanatory. Look at a few of the |
| keymaps that are distributed with Vim. For the details, see |mbyte-keymap|. |
| |
| |
| LAST RESORT |
| |
| If all other methods fail, you can enter any character with CTRL-V: |
| |
| encoding type range ~ |
| 8-bit CTRL-V 123 decimal 0-255 |
| 8-bit CTRL-V x a1 hexadecimal 00-ff |
| 16-bit CTRL-V u 013b hexadecimal 0000-ffff |
| 31-bit CTRL-V U 001303a4 hexadecimal 00000000-7fffffff |
| |
| Don't type the spaces. See |i_CTRL-V_digit| for the details. |
| |
| ============================================================================== |
| |
| Next chapter: |usr_90.txt| Installing Vim |
| |
| Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: |