diff --git a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc index 2391b8d257..5936175356 100644 --- a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc +++ b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc @@ -1,394 +1,394 @@ --- title: Chapter 9. PO Translations prev: books/fdp-primer/translations next: books/fdp-primer/weblate description: How to work with PO translation in the FreeBSD Documentation Project tags: ["po", "translations", "tutorial", "quick start"] showBookMenu: true weight: 9 params: path: "/books/fdp-primer/po-translations/" --- [[po-translations]] = PO Translations :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumoffset: 9 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[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 extref:{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/#. +. 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. + [source,shell] .... % mkdir ~/doc/documentation/content/es/articles/leap-seconds .... . Copy the [.filename]#_index.po# from the original document into the translation directory: + [source,shell] .... % cp ~/doc/documentation/content/en/articles/leap-seconds/_index.po \ ~/doc/documentation/content/es/articles/leap-seconds/ .... Suppose the document or language is also being translated via Weblate. In that case, it is good to get the `.po` file from there and upload the translation document back into the platform, centralizing the translating efforts via Weblate to avoid rework. See how to download the `.po` files in the crossref:weblate[weblate-translating-offline,Translating Offline on Weblate] chapter. ==== [[po-translations-quick-start-translation]] [.procedure] ==== .Procedure: Translation 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 % ./tools/translate.sh documentation es articles/leap-seconds .... + 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-bd# |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 crossref:overview[overview-quick-start, 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 extref:{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. [IMPORTANT] ==== Translating documents online proves to be the easiest method for document translation on FreeBSD, as it allows multiple users to collaborate on the same file, distributing the workload effectively. For more details, please refer to the next chapter, crossref:weblate[weblate-introduction,Weblate Translations]. ==== [[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 " "extref:{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 " "extref:{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. The Weblate chapter provides a complete example of how to crossref:weblate[weblate-building,Build the Translated Document]. [[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 .... ====== The Weblate chapter provides a complete example of how to crossref:weblate[weblate-submitting-translations,Submit the New Translation]. ==== diff --git a/documentation/content/en/books/fdp-primer/translations/_index.adoc b/documentation/content/en/books/fdp-primer/translations/_index.adoc index 06abcf1d35..6e8d67bbdb 100644 --- a/documentation/content/en/books/fdp-primer/translations/_index.adoc +++ b/documentation/content/en/books/fdp-primer/translations/_index.adoc @@ -1,252 +1,249 @@ --- title: Chapter 8. Translations prev: books/fdp-primer/rosetta next: books/fdp-primer/po-translations description: FAQ about the translation process in the FreeBSD Documentation Project tags: ["FAQ", "i18n", "i10n", "translation"] showBookMenu: true weight: 9 params: path: "/books/fdp-primer/translations/" --- [[translations]] = Translations :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumoffset: 8 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] This is the FAQ for people translating the FreeBSD documentation (FAQ, Handbook, tutorials, manual pages, and others) to different languages. It is _very_ heavily based on the translation FAQ from the FreeBSD German Documentation Project, originally written by Frank Gründer mailto:elwood@mc5sys.in-berlin.de[elwood@mc5sys.in-berlin.de] and translated back to English by Bernd Warken mailto:bwarken@mayn.de[bwarken@mayn.de]. == What do i18n and l10n mean? i18n means internationalization and l10n means localization. They are just a convenient shorthand. i18n can be read as "i" followed by 18 letters, followed by "n". Similarly, l10n is "l" followed by 10 letters, followed by "n". == Is there a mailing list for translators? Yes. Different translation groups have their own mailing lists. The https://www.freebsd.org/docproj/translations[list of translation projects] has more information about the mailing lists and web sites run by each translation project. In addition there is mailto:freebsd-translators@freebsd.org[freebsd-translators@freebsd.org] for general translation discussion. == Are more translators needed? Yes. The more people that work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents. You do not have to be a professional translator to be able to help. == What languages do I need to know? Ideally, you will have a good knowledge of written English, and obviously you will need to be fluent in the language you are translating to. English is not strictly necessary. For example, you could do a Hungarian translation of the FAQ from the Spanish translation. == What software do I need to know? It is strongly recommended that you maintain a local copy of the FreeBSD Git repository (at least the documentation part). This can be done by running: [source,shell] .... % git clone https://git.FreeBSD.org/doc.git ~/doc .... https://git.FreeBSD.org/[git.FreeBSD.org] is a public `git` server. [NOTE] ==== This will require the package:git-lite[] package to be installed. ==== You should be comfortable using git. This will allow you to see what has changed between different versions of the files that make up the documentation. For example, to view the differences between revisions `abff932fe8` and `2191c44469` of [.filename]#documentation/content/en/articles/committers-guide/_index.adoc#, run: [source,shell] .... % git diff abff932fe8 2191c44469 documentation/content/en/articles/committers-guide/_index.adoc .... Please see the complete explanation of using Git in FreeBSD in the extref:{handbook}mirrors[FreeBSD Handbook, git]. == How do I find out who else might be translating to the same language? The https://www.FreeBSD.org/docproj/translations/[Documentation Project translations page] lists the translation efforts that are currently known about. If others are already working on translating documentation to your language, please do not duplicate their efforts. Instead, contact them to see how you can help. If no one is listed on that page as translating for your language, then send a message to the {freebsd-doc} in case someone else is thinking of doing a translation, but has not announced it yet. == No one else is translating to my language. What do I do? Congratulations, you have just started the "FreeBSD _your-language-here_ Documentation Translation Project". Welcome aboard. First, decide whether or not you have got the time to spare. Since you are the only person working on your language at the moment it is going to be your responsibility to publicize your work and coordinate any volunteers that might want to help you. Write an email to the Documentation Project mailing list, announcing that you are going to translate the documentation, so the Documentation Project translations page can be maintained. If there is already someone in your country providing FreeBSD mirroring services you should contact them and ask if you can have some webspace for your project, and possibly an email address or mailing list services. Then pick a document and start translating. It is best to start with something fairly small - either the FAQ, or one of the tutorials. == I have translated some documentation, where do I send it? That depends. If you are already working with a translation team (such as the Japanese team, or the German team) then they will have their own procedures for handling submitted documentation, and these will be outlined on their web pages. If you are the only person working on a particular language (or you are responsible for a translation project and want to submit your changes back to the FreeBSD project) then you should send your translation to the FreeBSD project (see the next question). == I am the only person working on translating to this language, how do I submit my translation? First, make sure your translation is organized properly. This means that it should drop into the existing documentation tree and build straight away. -Directories below this are named according to the language code they are written in, -as defined in ISO639 ([.filename]#/usr/share/misc/iso639# on a version of FreeBSD newer than 20th January 1999). - [WARNING] ==== Hugo needs the language codes in lowercase. For example, instead of `pt_BR` Hugo uses `pt-br`. ==== Currently, the FreeBSD documentation is stored in a top level directory called [.filename]#documentation/#. Directories below this are named according to the language code they are written in, as defined in ISO639 ([.filename]#/usr/share/misc/iso639# on a version of FreeBSD newer than 20th January 1999). If your language can be encoded in different ways (for example, Chinese) then there should be directories below this, one for each encoding format you have provided. Finally, you should have directories for each document. For example, a hypothetical Swedish translation might look like: [.programlisting] .... documentation/ content/ sv/ books/ faq/ _index.adoc .... `sv` is the name of the translation, in [.filename]#lang# form. Note the two Makefiles, which will be used to build the documentation. Use git diff command to generate a diff and send it to the link:https://reviews.freebsd.org/[reviews system]. [source,shell] .... % git diff > sv-faq.diff .... You should use Bugzilla to link:https://bugs.freebsd.org/bugzilla/enter_bug.cgi[submit a report] indicating that you have submitted the documentation. It would be very helpful if you could get other people to look over your translation and double check it first, since it is unlikely that the person committing it will be fluent in the language. Someone (probably the Documentation Project Manager, currently {doceng}) will then take your translation and confirm that it builds. In particular, the following things will be looked at: . Does `make` in the [.filename]#root# directory work correctly? If there are any problems then whoever is looking at the submission will get back to you to work them out. If there are no problems your translation will be committed as soon as possible. == Can I include language or country specific text in my translation? We would prefer that you did not. For example, suppose that you are translating the Handbook to Korean, and want to include a section about retailers in Korea in your Handbook. There is no real reason why that information should not be in the English (or German, or Spanish, or Japanese, or ...) versions as well. It is feasible that an English speaker in Korea might try to pick up a copy of FreeBSD whilst over there. It also helps increase FreeBSD's perceived presence around the globe, which is not a bad thing. If you have country specific information, please submit it as a change to the English Handbook (using Bugzilla) and then translate the change back to your language in the translated Handbook. Thanks. === Addressing the reader In the English documents, the reader is addressed as "you", there is no formal/informal distinction as there is in some languages. If you are translating to a language which does distinguish, use whichever form is typically used in other technical documentation in your language. If in doubt, use a mildly polite form. === Do I need to include any additional information in my translations? Yes. The header of the English version of each document will look something like this: [.programlisting] .... --- title: Why you should use a BSD style license for your Open Source Project releaseinfo: "$FreeBSD: head/en_US.ISO8859-1/articles/bsdl-gpl/article.xml 53942 2020-03-01 12:23:40Z carlavilla $" trademarks: ["freebsd", "intel", "general"] --- = Why you should use a BSD style license for your Open Source Project .... The exact boilerplate may change, but it will always include a $FreeBSD$ line and the phrase `The FreeBSD Documentation Project`. Note that the $FreeBSD$ part is expanded automatically by Git, so it should be empty (just `$FreeBSD$`) for new files. Your translated documents should include their own FreeBSD line, and change the `FreeBSD Documentation Project` line to `The FreeBSD _language_ Documentation Project`. In addition, you should add a third line which indicates which revision of the English text this is based on. So, the Spanish version of this file might start: [.programlisting] .... --- title: Soporte para segundos intercalares en FreeBSD releaseinfo: "$FreeBSD: head/es_ES.ISO8859-1/articles/leap-seconds/article.xml 53090 2019-06-01 17:52:59Z carlavilla $" --- = Soporte para segundos intercalares en FreeBSD ....