TRANSLATING VIM MESSAGES

In this directory you will find xx.po files, where "xx" is a language code.
Each file contains the translation of English Vim messages for one language.
The files are in "po" format, used by the gettext package.  Please refer to
the gettext documentation for more information.

The GNU gettext library, starting with version 0.10.37, supports converting
messages from one encoding to another.  This requires that it was compiled
with HAVE_ICONV.  The result is that the messages may be in any encoding
supported by iconv and will be automatically converted to the currently used
encoding.

The GNU gettext library, starting with version 0.10.36, uses a new format for
some encodings.  This follows the C99 standard for strings.  It means that
when a multi-byte character includes the 0x5c byte, this is not recognized as
a backslash.  Since this format is incompatible with Solaris, Vim uses the old
format.  This is done by setting the OLD_PO_FILE_OUTPUT and OLD_PO_FILE_INPUT
environment variables.  When you use the Makefile in this directory that will
be done for you.  This does NOT work with gettext 0.10.36.  Don't use it, get
0.10.37.


ON MS-WINDOWS

The distributed files are generated on Unix, but this should also be possible
on MS-Windows.  Download the gettext packages, for example from:

	http://sourceforge.net/projects/gettext

You might have to do the commands manually.  Example:

   cd c:\vim\vim81
   mkdir runtime\lang\ja\LC_MESSAGES
   msgfmt -o runtime\lang\ja\LC_MESSAGES\vim.mo src\po\ja.po


WHEN THERE IS A MISTAKE

If you find there is a mistake in one of the translations, please report this
to the maintainer of the translation.  His/her E-mail address is in the
comments at the start of the file.  You can also see this with the ":messages"
command in Vim when the translation is being used.


CREATING A NEW PO FILE

We will use "xx.po" as an example here, replace "xx" with the name of your
language.

- Edit Makefile to add xx to LANGUAGES and xx.mo to MOFILES.
- If you haven't done so already, run ./configure in the top vim directory
  (i.e. go up two directories) and then come back here afterwards.
- Execute these commands:
  % make vim.pot
  % msginit -l xx
  % rm vim.pot
  The first command will generate a vim.pot file which is used by msginit to
  generate a correct xx.po file.  After that vim.pot is not needed.
- The remaining work is like updating, see the next section.


UPDATING A PO FILE

If you are the maintainer of a .po file, this is how you update the file.  We
will use "xx.po" as an example here, replace "xx" with the name of your
language.

(1) Add new and changed messages from the Vim sources:

	make xx

    This will extract all the strings from Vim and merge them in with the
    existing translations.  Requires the GNU gettext utilities.
    Your original xx.po file will be copied to xx.po.orig

    -- After you do this, you MUST do the next three steps! --

(2) Translate
    See the gettext documentation on how to do this.  You can also find
    examples in the other po files.  You can use "gF" on the file name to see
    the context of the message.
    Search the po file for items that require translation:

	/fuzzy\|^msgstr ""\(\n"\)\@!

    Remove the "#, fuzzy" line after adding the translation.

    There is one special message:
	msgid "Messages maintainer: Bram Moolenaar <[email protected]>"
    You should include your name and E-mail address instead, for example:
	msgstr "Berichten �bersetzt bei: John Doe <[email protected]>"

(3) Remove unused messages (optional)
    Remove messages that have been marked as obsolete.
    Such messages start with "#~".

    The cleanup script will also do that (see next step).

(4) Clean up
    This is very important to make sure the translation works on all systems.
    Comment-out all non-translated strings.  There are two types:
    - items marked with "#, fuzzy"
    - items with an empty msgstr
    You can do this with the cleanup.vim script:

	:source cleanup.vim

    Background: on Solaris an empty msgstr results in an empty message; GNU
    gettext ignores empty strings and items marked with "#, fuzzy".

    This also removes the line numbers from the file, so that patches are not
    messed up by changes in line numbers and show the actual changes in the
    text.

(5) Check:

    While editing the .po file:
        :source check.vim

    From the command line:
	vim -S check.vim xx.po
	make xx.mo

    Look out for syntax errors and fix them.

(6) Local tryout:
    Vim normally picks up the .mo files from:
	    $VIMRUNTIME/lang/{lang}/LC_MESSAGES/vim.mo
    To try out the messages with Vim use:
	    make tryoutinstall
    And run Vim with $VIMRUNTIME set to ../runtime


USING GETTEXT WITHOUT ICONV

When using gettext which doesn't support iconv, the encoding of the .mo file
must match your active encoding.  For that you must convert and change
encoding of *.po file in advance of generating the *.mo file.  For example, to
convert ja.po to EUC-JP (supposed as your system encoding):

(1) Convert the file encoding:

	mv ja.po ja.po.orig
	iconv -f utf-8 -t euc-jp ja.po.orig > ja.po

(2) Rewrite charset declaration in the file:

    Open ja.po find this line:
	"Content-Type: text/plain; charset=utf-8\n"
    You should change "charset" like this:
	"Content-Type: text/plain; charset=euc-jp\n"

There are examples in the Makefile for the conversions already supported.

TRANSLATING VIM MESSAGES

This file explains how to create and maintain po files using
gnu-gettext.win32, a MINGW32 Windows port of gettext by Franco Bez
<[email protected]>.  You can find it at:

	http://home.a-city.de/franco.bez/gettext/gettext_win32_en.html

First read the README.txt file for the general remarks


The file that does the work is Make_ming.mak in the po directory. It is an
adaptation of the Unix Makefile, but it does NOT test the presence of any po,
pot, or mo files, so use it at your own risk but with care: it could even kill
your canary. It has been tested by me several times (and with different
languages) with success.

The make utility must be run from the po directory.

First of all you must set the environment variable LANGUAGE to xx, where xx is
the name of your language. You can do it from the command line or adding a
line to your autoexec.bat file: set LANGUAGE=xx. You must also add your
language to the Make_ming.mak file in the lines LANGUAGES, MOFILES, AND
POFILES.

If you don't have a xx.po file, you must create it with the command:

	make -f Make_ming.mak first_time

This will produce a new brand xx.po file with all the messages in Vim ready
for translation. Then you must source the cleanup.vim script from inside Vim;
it will comment the untranslated messages (now, all). I recommend to use
syntax highlighting so you can identify the untranslated messages easily.
You also must remove the '..\' that prepends the name of the source files.
(I don't no why, but make is unable to change the directory from po to src and
back to po, so all the work must be done from the po dir, hence the '..\')

Then you must go step (2) below.

If you are updating a po file you must follow the next steps (they are nearly
the same as in the Unix case, only the commands change):

(1) Add new and changed messages from the Vim sources:

	make -f Make_ming.mak xx

    This will extract all the strings from Vim and merge them in with the
    existing translations.  Requires the GNU gettext utilities.  Also requires
    unpacking the extra archive.
    Your original xx.po file will be copied to xx.po.orig

    -- After you do this, you MUST do the next three steps! --

(2) Translate
    See the gettext documentation on how to do this.  You can also find
    examples in the other po files.
    Search the po file for items that require translation:
	/\#\~   and also the fuzzy translations, /\#, fuzzy
    Remove "#~" and "#, fuzzy" after adding the translation.

    There is one special message:
	msgid "Messages maintainer: Bram Moolenaar <[email protected]>"
    You should include your name and E-mail address instead, for example:
	msgstr "Berichten �bersetzt bei: John Doe <[email protected]>"

(3) Clean up
    This is very important to make sure the translation works on all systems.
    Comment-out all non-translated strings.  There are two types:
    - items marked with "#, fuzzy"
    - items with an empty msgstr
    You can do this with the cleanup.vim script:

	:source cleanup.vim

(4) Check:

	vim -S check.vim xx.po
	make -f Make_ming.mak xx.mo

    Look out for syntax errors and fix them.

(5) This is an extra step, ;-). If you want the vim.mo file installed in your
    system you must run:

	make -f Make_ming.mak install

    This will create the xx\LC_MESSAGES directory (if it does not exist) and
    will copy vim.po to it.
    You can also use the following command to install all languages:

	make -f Make_ming.mak install-all

(6) Another extra step ;-)). The command:

	make -f Make_ming.mak clean

    will delete the temp files created during the process.

Suggestions will be welcomed.

Eduardo F. Amatria <[email protected]>

Happy Vimming with NLS!!

vim:tw=78:

TRANSLATING VIM MESSAGES

This file explains how to create and maintain po files using a number of
GnuWin packages.  You will need gettext, libiconv and libexpat.  As of
August 2010 the versions known to work are gettext 0.14.4, libiconv 1.9.2-1
and expat 2.0.1.  gettext and libiconv can be found at:

	http://gnuwin32.sourceforge.net/

expat can be found at:

	http://sourceforge.net/projects/expat/

expat will install into its own directory.  You should copy libexpat.dll into
the bin directory created from the gettext/libiconv packages.

First read the README.txt file in this directory for general remarks on
translating Vim messages.


SETUP

Set the environment variable LANGUAGE to the language code for the language
you are translating Vim messages to.  Language codes are typically two
characters and you can find a list of them at:

	http://www.geocities.com/click2speak/languages.html

Another possibility is to use the gnuwin32 port of gettext. This is
recommended especially if you use already gnuwin32 tools to gunzip, bunzip,
patch etc. these files. You find the gnuwin32 version of gettext here:

        http://gnuwin32.sourceforge.net/packages/gettext.htm

Yet another very strait forward way is to get the sources of gettext from

        http://www.gnu.org/software/gettext/gettext.html

and build your own version of these tools. The documentation states that this
should be possible with MSVC4.0, MSVC5.0, MSVC6.0 or MSVC7.0, but you can
build it even successfully with MSVC8.0.

The LANGUAGE environment variable can be set from the command line, by adding
a line to your autoexec.bat file, or by defining a user variable from the
Advanced tab in the System control panel.

Next, edit Make_mvc.mak so that GETTEXT_PATH points the binary directory of
the installation.


CREATING A NEW TRANSLATION

When creating a new translation you must add your language code to the
Make_mvc.mak file in the lines defining LANGUAGES and MOFILES.  To create the
initial .po file for your language you must use the command:

	make -f make_mvc.mak first_time

Note: You need to be in the po directory when using this makefile.

Once you have your new .po file load it into Vim and source cleanup.vim, this
will convert untranslated messages to comments.  If you have syntax
highlighting turned on then untranslated messages will stand out more easily.

You will also need to edit the file names in the comments in the .po file.
You need to remove the absolute directory specification (which has the form
c:\vim61\src\).  You can do this in Vim with the following command with the
appropriate directory specification for where you have installed the Vim
source:

	%s/c:\\vim61\\src\\//g


UPDATING A TRANSLATION

If there are new or changed messages in Vim that need translating, then the
first thing to do is merge them into the existing translations.  This is done
with the following command:

	nmake -f Make_mvc.mak xx.po

where xx is the language code for the language needing translations.  The
original .po file is copied to xx.po.orig.


DOING THE TRANSLATION

Now that you have a .po file you can do the translations for all messages that
need it.  See README.txt for specific instructions.

Once you have finished translating the messages you should make sure all
non-translated strings are commented out.  This can be done by sourcing
cleanup.vim once again.


CHECKING THE TRANSLATION

Check the translation with the following command:

	nmake -f make_mvc.mak xx.mo

Correct any syntax errors reported.  When there are no more errors, the
translation is ready to be installed.


INSTALLING THE TRANSLATION

Install your translation with the following command:

	nmake -f make_mvc.mak install

This will create the xx\LC_MESSAGES directory in runtime\lang if it does not
already exist.
You can also use the following command to install all languages:

	nmake -f make_mvc.mak install-all


vim:tw=78: