12.3. Creating New Translations

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
LanguageRegionTranslated Directory NamePO File NameCharacter Set
EnglishUnited Statesen_US.ISO8859-1en_US.poISO 8859-1
DanishDenmarkda_DK.ISO8859-1da_DK.poISO 8859-1
GermanGermanyde_DE.ISO8859-1de_DE.poISO 8859-1
GreekGreeceel_GR.ISO8859-7el_GR.poISO 8859-7
SpanishSpaines_ES.ISO8859-1es_ES.poISO 8859-1
FrenchFrancefr_FR.ISO8859-1fr_FR.poISO 8859-1
HungarianHungaryhu_HU.ISO8859-2hu_HU.poISO 8859-2
ItalianItalyit_IT.ISO8859-15it_IT.poISO 8859-15
JapaneseJapanja_JP.eucJPja_JP.poEUC JP
DutchNetherlandsnl_NL.ISO8859-1nl_NL.poISO 8859-1
PolishPolandpl_PL.ISO8859-2pl_PL.poISO 8859-2
PortugueseBrazilpt_BR.ISO8859-1pt_BR.poISO 8859-1
TurkishTurkeytr_TR.ISO8859-9tr_TR.poISO 8859-9

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/.

  1. 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
  2. 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.
    DOC?= book
    FORMATS?= html-split
    # 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/.

  1. 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
  2. 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. As 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
    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.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.