12.3. Creating New Translations

12.3. Creating New Translations
Prev	Chapter 12. PO Translations	Next

The first step to creating a new translated document is locating or creating a directory to hold it. FreeBSD puts translated documents in a subdirectory named for their language and region in the format lang_REGION. lang is a two-character lowercase code. It is followed by an underscore character and then the two-character uppercase REGION code.

Table 12.1. Language Names

Language	Region	Translated Directory Name	PO File Name	Character Set
English	United States	`en_US.ISO8859-1`	`en_US.po`	ISO 8859-1
Bengali	Bangladesh	`bn_BD.UTF-8`	`bn_BD.po`	UTF-8
Danish	Denmark	`da_DK.ISO8859-1`	`da_DK.po`	ISO 8859-1
German	Germany	`de_DE.ISO8859-1`	`de_DE.po`	ISO 8859-1
Greek	Greece	`el_GR.ISO8859-7`	`el_GR.po`	ISO 8859-7
Spanish	Spain	`es_ES.ISO8859-1`	`es_ES.po`	ISO 8859-1
French	France	`fr_FR.ISO8859-1`	`fr_FR.po`	ISO 8859-1
Hungarian	Hungary	`hu_HU.ISO8859-2`	`hu_HU.po`	ISO 8859-2
Italian	Italy	`it_IT.ISO8859-15`	`it_IT.po`	ISO 8859-15
Japanese	Japan	`ja_JP.eucJP`	`ja_JP.po`	EUC JP
Korean	Korea	`ko_KR.UTF-8`	`ko_KR.po`	UTF-8
Mongolian	Mongolia	`mn_MN.UTF-8`	`mn_MN.po`	UTF-8
Dutch	Netherlands	`nl_NL.ISO8859-1`	`nl_NL.po`	ISO 8859-1
Polish	Poland	`pl_PL.ISO8859-2`	`pl_PL.po`	ISO 8859-2
Portuguese	Brazil	`pt_BR.ISO8859-1`	`pt_BR.po`	ISO 8859-1
Russian	Russia	`ru_RU.KOI8-R`	`ru_RU.po`	KOI8-R
Turkish	Turkey	`tr_TR.ISO8859-9`	`tr_TR.po`	ISO 8859-9
Chinese	China	`zh_CN.UTF-8`	`zh_CN.po`	UTF-8
Chinese	Taiwan	`zh_TW.UTF-8`	`zh_TW.po`	UTF-8

The translations are in subdirectories of the main documentation directory, here assumed to be ~/doc/ as shown in Section 1.1, “Quick Start”. For example, German translations are located in ~/doc/de_DE.ISO8859-1/, and French translations are in ~/doc/fr_FR.ISO8859-1/.

Each language directory contains separate subdirectories named for the type of documents, usually articles/ and books/.

Combining these directory names gives the complete path to an article or book. For example, the French translation of the NanoBSD article is in ~/doc/fr_FR.ISO8859-1/articles/nanobsd/, and the Mongolian translation of the Handbook is in ~/doc/mn_MN.UTF-8/books/handbook/.

A new language directory must be created when translating a document to a new language. If the language directory already exists, only a subdirectory in the articles/ or books/ directory is needed.

FreeBSD documentation builds are controlled by a Makefile in the same directory. With simple articles, the Makefile can often just be copied verbatim from the original English directory. The translation process combines multiple separate book.xml and chapter.xml files in books into a single file, so the Makefile for book translations must be copied and modified.

Example 12.1. Creating a Spanish Translation of the Porter's Handbook

Create a new Spanish translation of the Porter's Handbook. The original is a book in ~/doc/en_US.ISO8859-1/books/porters-handbook/.

The Spanish language books directory ~/doc/es_ES.ISO8859-1/books/ already exists, so only a new subdirectory for the Porter's Handbook is needed:
```
% cd ~/doc/es_ES.ISO8859-1/books/
% svn mkdir porters-handbook
A         porters-handbook
```

Copy the Makefile from the original book:

% cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
% svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .
A         Makefile

Modify the contents of the Makefile to only expect a single book.xml:

#
# $FreeBSD$
#
# Build the FreeBSD Porter's Handbook.
#

MAINTAINER=doc@FreeBSD.org

DOC?= book

FORMATS?= html-split

INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=

# XML content
SRCS=  book.xml

# Images from the cross-document image library
IMAGES_LIB+=    callouts/1.png
IMAGES_LIB+=    callouts/2.png
IMAGES_LIB+=    callouts/3.png
IMAGES_LIB+=    callouts/4.png
IMAGES_LIB+=    callouts/5.png
IMAGES_LIB+=    callouts/6.png
IMAGES_LIB+=    callouts/7.png
IMAGES_LIB+=    callouts/8.png
IMAGES_LIB+=    callouts/9.png
IMAGES_LIB+=    callouts/10.png
IMAGES_LIB+=    callouts/11.png
IMAGES_LIB+=    callouts/12.png
IMAGES_LIB+=    callouts/13.png
IMAGES_LIB+=    callouts/14.png
IMAGES_LIB+=    callouts/15.png
IMAGES_LIB+=    callouts/16.png
IMAGES_LIB+=    callouts/17.png
IMAGES_LIB+=    callouts/18.png
IMAGES_LIB+=    callouts/19.png
IMAGES_LIB+=    callouts/20.png
IMAGES_LIB+=    callouts/21.png

URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..

.include "${DOC_PREFIX}/share/mk/doc.project.mk"

Now the document structure is ready for the translator to begin translating with make po.

Example 12.2. Creating a French Translation of the PGP Keys Article

Create a new French translation of the PGP Keys article. The original is an article in ~/doc/en_US.ISO8859-1/articles/pgpkeys/.

The French language article directory ~/doc/fr_FR.ISO8859-1/articles/ already exists, so only a new subdirectory for the PGP Keys article is needed:
```
% cd ~/doc/fr_FR.ISO8859-1/articles/
% svn mkdir pgpkeys
A         pgpkeys
```

Copy the Makefile from the original article:

% cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys
% svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .
A         Makefile

Check the contents of the Makefile. Because this is a simple article, in this case the Makefile can be used unchanged. The $FreeBSD...$ version string on the second line will be replaced by the version control system when this file is committed.

#
# $FreeBSD$
#
# Article: PGP Keys

DOC?= article

FORMATS?= html
WITH_ARTICLE_TOC?= YES

INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=

SRCS=   article.xml

# To build with just key fingerprints, set FINGERPRINTS_ONLY.

URL_RELPREFIX?= ../../../..
DOC_PREFIX?=    ${.CURDIR}/../../..

.include "${DOC_PREFIX}/share/mk/doc.project.mk"

With the document structure complete, the PO file can be created with make po.

Prev	Up	Next
12.2. Quick Start	Home	12.4. Translating