diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile index a1be3e53f1..e61cbd6a68 100644 --- a/en_US.ISO8859-1/books/fdp-primer/Makefile +++ b/en_US.ISO8859-1/books/fdp-primer/Makefile @@ -31,6 +31,7 @@ SRCS+= xhtml-markup/chapter.xml SRCS+= docbook-markup/chapter.xml SRCS+= stylesheets/chapter.xml SRCS+= translations/chapter.xml +SRCS+= po-translations/chapter.xml SRCS+= writing-style/chapter.xml SRCS+= editor-config/chapter.xml SRCS+= see-also/chapter.xml diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml index d2f55c69b5..21d50e7157 100644 --- a/en_US.ISO8859-1/books/fdp-primer/book.xml +++ b/en_US.ISO8859-1/books/fdp-primer/book.xml @@ -258,6 +258,7 @@ The time is 09:18 &chap.docbook-markup; &chap.stylesheets; &chap.translations; + &chap.po-translations; &chap.writing-style; &chap.editor-config; &chap.see-also; diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent index 81278d507e..55c9cdcf53 100644 --- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent +++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent @@ -21,6 +21,7 @@ + diff --git a/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml new file mode 100644 index 0000000000..6e779167e1 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/po-translations/chapter.xml @@ -0,0 +1,760 @@ + + + + + <acronym>PO</acronym> Translations + + + Introduction + + 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. + + + + Quick Start + + 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: + + &prompt.root; make -C /usr/ports/textproc/docproj config + + Then reinstall the + textproc/docproj port. + + This example shows the creation of a Spanish translation of + the short Leap + Seconds article. + + + Install a <acronym>PO</acronym> Editor + + + 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 + + + + + Initial Setup + + 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/ + + + + + Translation + + 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 and underline and a + two-character region code. For Spanish, the file name is + es_ES.po. + + &prompt.user; poedit es_ES.po + + + + + Generating a Translated Document + + + 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 + + + + + + Creating New Translations + + 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 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 + + + + 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. + + + 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: + &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. + + + + + + Creating a French Translation of the + <acronym>PGP</acronym> 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: + &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. + + + + + + + Translating + + 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. + + + Translating the Porter's Handbook to Spanish + + 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 + + + + + + + Tips for Translators + + + Preserving <acronym>XML</acronym> Tags + + 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 + + + + + Preserving Spaces + + Preserve existing spaces at the beginning and end of + strings to be translated. The translated version must have + these spaces also. + + + + Verbatim Tags + + The contents of some tags should be copied verbatim, not + translated: + + + + citerefentry + + + + command + + + + filename + + + + literal + + + + manvolnum + + + + orgname + + + + package + + + + programlisting + + + + prompt + + + + refentrytitle + + + + screen + + + + userinput + + + + varname + + + + + + + + + Building a Translated Document + + 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. + + + Building the Spanish Porter's Handbook + + 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 + + + + +