start

# txt2po and po2txt

txt2po allows you to use the same principles of PO files with normal text files. In PO only items that change are marked fuzzy and only new items need to be translated, unchanged items remain unchanged for the translation.

## Usage

    txt2po [options] <foo.txt> <foo.po>
    po2txt [options] [-t <foo.txt>] <XX.po> <foo-XX.txt>

Where:

foo.txt | is the input plain text file
foo.po | is an empty PO file that may be translated
XX.po | is a PO file translted into the XX language
foo-XX.txt | is the foo.txt file translated into language XX

Options (txt2po):

--version | show program’s version number and exit
-h, --help | show this help message and exit
--manpage | output a manpage based on the help
--progress=PROGRESS | show progress as: dots, none, bar, names, verbose
--errorlevel=ERRORLEVEL | show errorlevel as: none, message, exception, traceback
-iINPUT, --input=INPUT | read from INPUT in *, txt formats
-xEXCLUDE, --exclude=EXCLUDE | exclude names matching EXCLUDE from input paths
-oOUTPUT, --output=OUTPUT | write to OUTPUT in po, pot formats
--psyco=MODE | use psyco to speed up the operation, modes: none, full, profile
-P, --pot | output PO Templates (.pot) rather than PO files (.po)
--flavour | indicate the type of txt file, plain (default), dokuwiki, mediawiki (since 1.0)
--encoding | encoding of the input file (since 1.0)

Options (po2txt):

--version | show program’s version number and exit
-h, --help | show this help message and exit
--manpage | output a manpage based on the help
--progress=PROGRESS | show progress as: dots, none, bar, names, verbose
--errorlevel=ERRORLEVEL | show errorlevel as: none, message, exception, traceback
-iINPUT, --input=INPUT | read from INPUT in po, pot formats
-xEXCLUDE, --exclude=EXCLUDE | exclude names matching EXCLUDE from input paths
-oOUTPUT, --output=OUTPUT | write to OUTPUT in txt format
-tTEMPLATE, --template=TEMPLATE | read from TEMPLATE in txt format
--psyco=MODE | use psyco to speed up the operation, modes: none, full, profile
-wWRAP, --wrap=WRAP | set number of columns to wrap text at
--fuzzy | use translations marked fuzzy
--nofuzzy | don’t use translations marked fuzzy (default)
--encoding | encoding of the template file (since 1.0)

## A roundtrip example

### Preparing input files

With txt2po a text file is broken down into sections. Each section is seperated by a line of whitespace. Each section will appear as a msgid in the PO file. Because of this simple method of breaking up the input file it might be necisary to alter the layout of your input file. For instance you might want to seperate a heading from a paragraph by using whitespace.

For steps in a process you would want to leave a blank line between each step so that each step can be translated independently.

For a list of items you might want to group them together so that a translator could for example place them in alphabetic order for their translation.

Once the input file is prepared you can proceed to the next step.

### Creating the POT files

This is simple:

    txt2po -P TEXT_FILE text_file.pot

A translator would copy the POT file to their own PO file and then create translations of the entries. If you wish to create a PO file and not a POT file then leave off the -P option.

You might want to manually edit the POT file to remove items that should not be translated. For instance if part of the document is a license you might want to remove those if you do not want the license translated for legal reasons.

### Translating

Translate as normal. However translators should be aware that writers of the text file may have used spaces, dashes, equals, underscores and other aids to indicate things such as:

- Headings and sub-headings
- Code examples, command lines examples
- Various lists
- etc

They will need to adapt these to work in their language being aware of how they will appear once they are merged with the original text document.

### Creating a translated text file

With the translations complete you can create a translated text file like this:

    po2txt -w 75 -t TEXT_FILE translated.po TEXT_FILE.translated

This uses the original text file as a template and creates a new translated text file using the translations found in the PO file.

The -w command allows you to reflow the translated text to N number of characters, otherwise the text will appear as one long line.