The GNU gettext system offers translators an easy way to create and maintain translations of documents. Translatable strings are extracted from the original document into a PO (Portable Object) file. Translated versions of the strings are entered with a separate editor. The strings can be used directly or built into a complete translated version of the original document. The procedure shown in is assumed to have already been performed, but the TRANSLATOR option must be enabled in the textproc/docproj port. If that option was not enabled, display the options menu and enable it, then reinstall the port: &prompt.root; cd /usr/ports/textproc/docproj &prompt.root; make config &prompt.root; make clean deinstall install clean This example shows the creation of a Spanish translation of the short Leap Seconds article. A PO editor is needed to edit translation files. This example uses editors/poedit. &prompt.root; cd /usr/ports/editors/poedit &prompt.root; make install clean When a new translation is first created, the directory structure and Makefile must be created or copied from the English original: Create a directory for the new translation. The English article source is in ~/doc/en_US.ISO8859-1/articles/leap-seconds/. The Spanish translation will go in ~/doc/es_ES.ISO8859-1/articles/leap-seconds/. The path is the same except for the name of the language directory. &prompt.user; svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ Copy the Makefile from the original document into the translation directory: &prompt.user; svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \ ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ Translating a document consists of two steps: extracting translatable strings from the original document, and entering translations for those strings. These steps are repeated until the translator feels that enough of the document has been translated to produce a usable translated document. Extract the translatable strings from the original English version into a PO file: &prompt.user; cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ &prompt.user; make po Use a PO editor to enter translations in the PO file. There are several different editors available. poedit from editors/poedit is shown here. The PO file name is the two-character language code followed by an underline and a two-character region code. For Spanish, the file name is es_ES.po. &prompt.user; poedit es_ES.po Generate the translated document: &prompt.user; cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ &prompt.user; make tran The name of the generated document matches the name of the English original, usually article.xml for articles or book.xml for books. Check the generated file by rendering it to HTML and viewing it with a web browser: &prompt.user; make FORMATS=html &prompt.user; firefox article.html The first step to creating a new translated document is locating or creating a directory to hold it. &os; 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. 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 Norwegian Norway no_NO.ISO8859-1 no_NO.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 Serbian Serbia sr_YU.ISO8859-2 sr_YU.po ISO 8859-2 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 . 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. &os; 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. 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: &prompt.user; cd ~/doc/es_ES.ISO8859-1/books/ &prompt.user; svn mkdir porters-handbook A porters-handbook Copy the Makefile from the original book: &prompt.user; cd ~/doc/es_ES.ISO8859-1/books/porters-handbook &prompt.user; 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}/../../.. SYMLINKS= ${DESTDIR} index.html handbook.html .include "${DOC_PREFIX}/share/mk/doc.project.mk" Now the document structure is ready for the translator to begin translating with make po. 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: &prompt.user; cd ~/doc/fr_FR.ISO8859-1/articles/ &prompt.user; svn mkdir pgpkeys A pgpkeys Copy the Makefile from the original article: &prompt.user; cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys &prompt.user; 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 $&os;...$ version string on the third 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. The gettext system greatly reduces the number of things that must be tracked by a translator. Strings to be translated are extracted from the original document into a PO file. Then a PO editor is used to enter the translated versions of each string. The &os; PO translation system does not overwrite PO files, so the extraction step can be run at any time to update the PO file. A PO editor is used to edit the file. editors/poedit is shown in these examples because it is simple and has minimal requirements. Other PO editors offer features to make the job of translating easier. The Ports Collection offers several of these editors, including devel/gtranslator. It is important to preserve the PO file. It contains all of the work that translators have done. Enter Spanish translations of the contents of the Porter's Handbook. Change to the Spanish Porter's Handbook directory and update the PO file. The generated PO file is called es_ES.po as shown in . &prompt.user; cd ~/doc/es_ES.ISO8859-1/books/porters-handbook &prompt.user; make po Enter translations using a PO editor: &prompt.user; poedit es_ES.po Preserve XML tags that are shown in the English original. English original: If acronymNTPacronym is not being used Spanish translation: Si acronymNTPacronym no se utiliza Preserve existing spaces at the beginning and end of strings to be translated. The translated version must have these spaces also. The contents of some tags should be copied verbatim, not translated: citerefentry command filename literal manvolnum orgname package programlisting prompt refentrytitle screen userinput varname A translated version of the original document can be created at any time. Any untranslated portions of the original will be included in English in the resulting document. Most PO editors have an indicator that shows how much of the translation has been completed. This makes it easy for the translator to see when enough strings have been translated to make building the final document worthwhile. Build and preview the Spanish version of the Porter's Handbook that was created in an earlier example. Build the translated document. Because the original is a book, the generated document is book.xml. &prompt.user; cd ~/doc/es_ES.ISO8859-1/books/porters-handbook &prompt.user; make tran Render the translated book.xml to HTML and view it with Firefox. This is the same procedure used with the English version of the documents, and other FORMATS can be used here in the same way. See . &prompt.user; make FORMATS=html &prompt.user; firefox book.html