mirror of https://git.FreeBSD.org/doc.git
420 lines
12 KiB
Plaintext
420 lines
12 KiB
Plaintext
---
|
|
title: Chapter 9. PO Translations
|
|
prev: books/fdp-primer/translations
|
|
next: books/fdp-primer/manual-pages
|
|
description: How to work with PO translation in the FreeBSD Documentation Project
|
|
---
|
|
|
|
[[po-translations]]
|
|
= PO Translations
|
|
:doctype: book
|
|
:toc: macro
|
|
:toclevels: 1
|
|
:icons: font
|
|
:sectnums:
|
|
:sectnumlevels: 6
|
|
:source-highlighter: rouge
|
|
:experimental:
|
|
:skip-front-matter:
|
|
:xrefstyle: basic
|
|
:relfileprefix: ../
|
|
:outfilesuffix:
|
|
:sectnumoffset: 9
|
|
|
|
include::shared/en/urls.adoc[]
|
|
|
|
toc::[]
|
|
|
|
[[po-translations-introduction]]
|
|
== Introduction
|
|
|
|
The http://www.gnu.org/software/gettext/[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.
|
|
|
|
[[po-translations-quick-start]]
|
|
== Quick Start
|
|
|
|
The procedure shown in crossref:overview[overview-quick-start,Quick Start] is assumed to have already been performed.
|
|
The `TRANSLATOR` option is required and already enabled by default in the package:textproc/docproj[] port.
|
|
|
|
This example shows the creation of a Spanish translation of the short link:{leap-seconds}[Leap Seconds] article.
|
|
|
|
[[po-translations-quick-start-install-po-editor]]
|
|
|
|
[.procedure]
|
|
====
|
|
.Procedure: Install a PO Editor
|
|
. A PO editor is needed to edit translation files. This example uses package:editors/poedit[].
|
|
+
|
|
[source,shell]
|
|
....
|
|
# pkg install poedit
|
|
....
|
|
====
|
|
|
|
[[po-translations-quick-start-initial-setup]]
|
|
[.procedure]
|
|
====
|
|
.Procedure: Initial Setup
|
|
|
|
When a new translation is first created, the directory structure must be created or copied from the English original:
|
|
|
|
. Create a directory for the new translation. The English article source is in [.filename]#~/doc/documentation/content/en/articles/leap-seconds/#. The Spanish translation will go in [.filename]#~/doc/documentation/content/es/articles/leap-seconds/#. The path is the same except for the name of the language directory.
|
|
The English article source is in [.filename]#~/doc/en/articles/leap-seconds/#.
|
|
The Spanish translation will go in [.filename]#~/doc/es/articles/leap-seconds/#.
|
|
The path is the same except for the name of the language directory.
|
|
+
|
|
[source,shell]
|
|
....
|
|
% mkdir ~/doc/documentation/content/es/articles/leap-seconds
|
|
....
|
|
|
|
. Copy the [.filename]#_index.adoc# from the original document into the translation directory:
|
|
+
|
|
[source,shell]
|
|
....
|
|
% cp ~/doc/documentation/content/en/articles/leap-seconds/_index.adoc \
|
|
~/doc/documentation/content/es/articles/leap-seconds/
|
|
....
|
|
====
|
|
|
|
[[po-translations-quick-start-translation]]
|
|
[.procedure]
|
|
====
|
|
.Procedure: 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:
|
|
+
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc
|
|
% po4a-gettextize \
|
|
--format asciidoc \
|
|
--option compat=asciidoctor \
|
|
--option yfm_keys=title,part \
|
|
--master "documentation/content/en/articles/leap-seconds/_index.adoc" \
|
|
--master-charset "UTF-8" \
|
|
--copyright-holder "The FreeBSD Project" \
|
|
--package-name "FreeBSD Documentation" \
|
|
--po "documentation/content/es/articles/leap-seconds/_index.po"
|
|
....
|
|
+
|
|
. Use a PO editor to enter translations in the PO file. There are several different editors available. [.filename]#poedit# from package:editors/poedit[] is shown here.
|
|
+
|
|
[source,shell]
|
|
....
|
|
% poedit documentation/content/es/articles/leap-seconds/_index.po
|
|
....
|
|
====
|
|
|
|
[[po-translations-quick-generating-a-translated-document]]
|
|
[.procedure]
|
|
====
|
|
.Procedure: Generating a Translated Document
|
|
. Generate the translated document:
|
|
+
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc
|
|
% po4a-translate \
|
|
--format asciidoc \
|
|
--option compat=asciidoctor \
|
|
--option yfm_keys=title,part \
|
|
--master "documentation/content/en/articles/leap-seconds/_index.adoc" \
|
|
--master-charset "UTF-8" \
|
|
--po "documentation/content/es/articles/leap-seconds/_index.po" \
|
|
--localized "documentation/content/es/articles/leap-seconds/_index.adoc" \
|
|
--localized-charset "UTF-8" \
|
|
--keep 0
|
|
....
|
|
+
|
|
The name of the generated document matches the name of the English original, usually [.filename]#_index.adoc#.
|
|
+
|
|
. Check the generated file by rendering it to HTML and viewing it with a web browser:
|
|
+
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc/documentation
|
|
% make
|
|
....
|
|
====
|
|
|
|
[[po-translations-creating]]
|
|
== 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 [.filename]#lang#.
|
|
_lang_ is a two-character lowercase code.
|
|
|
|
[[po-translations-language-names]]
|
|
.Language Names
|
|
[cols="1,1,1", frame="none", options="header"]
|
|
|===
|
|
| Language
|
|
| Region
|
|
| Translated Directory Name
|
|
|
|
|English
|
|
|United States
|
|
|[.filename]#en#
|
|
|
|
|Bengali
|
|
|Bangladesh
|
|
|[.filename]#bn#
|
|
|
|
|Danish
|
|
|Denmark
|
|
|[.filename]#da#
|
|
|
|
|German
|
|
|Germany
|
|
|[.filename]#de#
|
|
|
|
|Greek
|
|
|Greece
|
|
|[.filename]#el#
|
|
|
|
|Spanish
|
|
|Spain
|
|
|[.filename]#es#
|
|
|
|
|French
|
|
|France
|
|
|[.filename]#fr#
|
|
|
|
|Hungarian
|
|
|Hungary
|
|
|[.filename]#hu#
|
|
|
|
|Italian
|
|
|Italy
|
|
|[.filename]#it#
|
|
|
|
|Japanese
|
|
|Japan
|
|
|[.filename]#ja#
|
|
|
|
|Korean
|
|
|Korea
|
|
|[.filename]#ko#
|
|
|
|
|Mongolian
|
|
|Mongolia
|
|
|[.filename]#mn#
|
|
|
|
|Dutch
|
|
|Netherlands
|
|
|[.filename]#nl#
|
|
|
|
|Polish
|
|
|Poland
|
|
|[.filename]#pl#
|
|
|
|
|Portuguese
|
|
|Brazil
|
|
|[.filename]#pt-br#
|
|
|
|
|Russian
|
|
|Russia
|
|
|[.filename]#ru#
|
|
|
|
|Turkish
|
|
|Turkey
|
|
|[.filename]#tr#
|
|
|
|
|Chinese
|
|
|China
|
|
|[.filename]#zh-cn#
|
|
|
|
|Chinese
|
|
|Taiwan
|
|
|[.filename]#zh-tw#
|
|
|===
|
|
|
|
The translations are in subdirectories of the main documentation directory,
|
|
here assumed to be [.filename]#~/doc/documentation/# as shown in <<overview-quick-start>>.
|
|
For example, German translations are located in [.filename]#~/doc/documentation/content/de/#,
|
|
and French translations are in [.filename]#~/doc/documentation/content/fr/#.
|
|
|
|
Each language directory contains separate subdirectories named for the type of documents, usually [.filename]#articles/# and [.filename]#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 [.filename]#~/doc/documentation/content/fr/articles/nanobsd/#,
|
|
and the Mongolian translation of the Handbook is in [.filename]#~/doc/documentation/content/mn/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 [.filename]#articles/# or [.filename]#books/# directory is needed.
|
|
|
|
[[po-translations-creating-example]]
|
|
.Creating a Spanish Translation of the Porter's Handbook
|
|
[example]
|
|
====
|
|
Create a new Spanish translation of the link:{porters-handbook}[Porter's Handbook].
|
|
The original is a book in [.filename]#~/doc/documentation/content/en/books/porters-handbook/#.
|
|
|
|
[.procedure]
|
|
======
|
|
|
|
. The Spanish language books directory [.filename]#~/doc/documentation/content/es/books/# already exists, so only a new subdirectory for the Porter's Handbook is needed:
|
|
+
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc/documentation/content/es/books
|
|
% mkdir porters-handbook
|
|
....
|
|
|
|
. Copy the content from the original book:
|
|
+
|
|
[source,shell]
|
|
....
|
|
% cd porters-handbook
|
|
% cp -R ~/doc/documentation/content/en/books/porters-handbook/* .
|
|
....
|
|
+
|
|
Now the document structure is ready for the translator to begin translating with `po4a` command.
|
|
======
|
|
====
|
|
|
|
[[po-translations-translating]]
|
|
== 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 FreeBSD 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.
|
|
package: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 package:devel/gtranslator[].
|
|
|
|
It is important to preserve the PO file.
|
|
It contains all of the work that translators have done.
|
|
|
|
[[po-translations-translating-example]]
|
|
.Translating the Porter's Handbook to Spanish
|
|
[example]
|
|
====
|
|
|
|
[.procedure]
|
|
======
|
|
. Change to the base directory and update all PO files.
|
|
+
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc
|
|
% po4a-gettextize \
|
|
--format asciidoc \
|
|
--option compat=asciidoctor \
|
|
--option yfm_keys=title,part \
|
|
--master "documentation/content/en/books/porters-handbook/_index.adoc" \
|
|
--master-charset "UTF-8" \
|
|
--copyright-holder "The FreeBSD Project" \
|
|
--package-name "FreeBSD Documentation" \
|
|
--po "documentation/content/es/books/porters-handbook/_index.po"
|
|
....
|
|
|
|
. Enter translations using a PO editor:
|
|
+
|
|
[source,shell]
|
|
....
|
|
% poedit documentation/content/es/books/porters-handbook/_index.po
|
|
....
|
|
======
|
|
|
|
These steps are necessary for all `.adoc` files, excluding `chapters-order.adoc` and `toc-*.adoc`.
|
|
|
|
====
|
|
|
|
[[po-translations-tips]]
|
|
== Tips for Translators
|
|
|
|
[[po-translations-tips-xmltags]]
|
|
=== Preserving AsciiDoc macros
|
|
|
|
Preserve AsciiDoc macros that are shown in the English original.
|
|
|
|
.Preserving AsciiDoc macros
|
|
[example]
|
|
====
|
|
English original:
|
|
|
|
[.programlisting]
|
|
....
|
|
msgid ""
|
|
"This example shows the creation of a Spanish translation of the short "
|
|
"link:{leap-seconds}[Leap Seconds] article."
|
|
....
|
|
|
|
Spanish translation:
|
|
|
|
[.programlisting]
|
|
....
|
|
msgid ""
|
|
"Este ejemplo muestra la creación de un artículo con poco contenido como el artículo "
|
|
"link:{leap-seconds}[Leap Seconds]."
|
|
....
|
|
|
|
====
|
|
|
|
[[po-translations-tips-spaces]]
|
|
=== Preserving Spaces
|
|
|
|
Preserve existing spaces at the beginning and end of strings to be translated.
|
|
The translated version must have these spaces also.
|
|
|
|
[[po-translations-tips-verbatim]]
|
|
=== Verbatim Tags
|
|
|
|
The contents of some tags should be copied verbatim, not translated:
|
|
|
|
* `man:man[1]`
|
|
* `package:package[]`
|
|
* `link`
|
|
* `image`
|
|
* `include`
|
|
* `Admonitions`
|
|
* `id's`
|
|
* `Heading tags`
|
|
* `source`
|
|
|
|
[[po-translations-building]]
|
|
== 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.
|
|
|
|
[[po-translations-submitting]]
|
|
== Submitting the New Translation
|
|
|
|
Prepare the new translation files for submission.
|
|
This includes adding the files to the version control system, setting additional properties on them, then creating a diff for submission.
|
|
|
|
The diff files created by these examples can be attached to a https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation[documentation bug report] or https://reviews.freebsd.org/[code review].
|
|
|
|
[[po-translations-submitting-spanish]]
|
|
.Spanish Translation of the NanoBSD Article
|
|
[example]
|
|
====
|
|
[.procedure]
|
|
======
|
|
|
|
. Create a diff of the new files from the [.filename]#~/doc/# base directory so the full path is shown with the filenames. This helps committers identify the target language directory.
|
|
+
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc
|
|
% git diff documentation/content/es/articles/nanobsd/ > /tmp/es_nanobsd.diff
|
|
....
|
|
======
|
|
|
|
====
|