doc:translation:weblate

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
doc:translation:weblate [2021/03/14 22:11] – Add `Translation based on Automatic Suggestions` section DaniloBaiodoc:translation:weblate [2023/06/24 16:38] (current) – Link with books/fdp-primer DaniloBaio
Line 1: Line 1:
 ====== Translate FreeBSD on Weblate ====== ====== Translate FreeBSD on Weblate ======
  
-===== Introduction ===== +See [[https://docs.freebsd.org/en/books/fdp-primer/weblate/|books/fdp-primer/Weblate Translations]] chapter.
- +
-This article describes some basic steps on how to join the translators team of %%FreeBSD%%, how to translate on Weblate or Offline, as well as some simple suggestions on translating, proofreading and testing. +
-It's focused on the translation part, if you are interested in more details about the documents structure, see the book "%%FreeBSD%% Documentation Project Primer for New Contributors" on https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/. +
- +
-[[https://weblate.org/en/|Weblate]] is an open source software web-based focused on localization, we run our own local instance. +
- +
-===== How to become a FreeBSD translator ===== +
- +
-Simple steps to start translating articles and books of the %%FreeBSD%% Documentation Project, you can see the original documents on https://www.freebsd.org/doc/en/. +
- +
-* Create an account, with an email address or with your Github login. +
- +
-* Subscribe to the [[https://lists.freebsd.org/mailman/listinfo/freebsd-translators|freebsd-translators mailing list]]. +
- +
-* Introduce Yourself and ask to join on some language team. (If the language team does not exist, ask for creating it, you could be the coordinator). +
- +
-* Login to Weblate with your new account. +
- +
-* Find your language team and choose an initial document to translate. +
- +
-Your self-introduction is important. It raises your chances to be approved for write access. You may also want to create a Bugzilla account to submit the translations after finishing a document. +
- +
-All translation files and translated documents need to follow [[https://www.freebsd.org/copyright/freebsd-doc-license.html|The FreeBSD Documentation License]], if this is not acceptable, please do not sign up or send any patches or translations. +
- +
-===== Introduce Yourself ===== +
- +
-Make a short self-introduction to the mailing list freebsd-translators you have subscribed. The purpose of this is to allow a language coordinator to grant access to you, so you will be able to translate on Weblate or to ask one of the administrator to create a new language on the project for you. +
- +
-Following is an example of how such an email could look like. +
- +
-<code> +
-Subject +
- +
-Self-Introduction: Your name and language +
- +
-Body +
- +
-Name: Your name (use preferred name) +
-Location: City, country (optional) +
-Login: username or email (essential) +
-Language: Language to translate (essential) +
-Profession or student status: (optional) +
-About You: (free format - your info which you feel comfortable to share with others: company, school, other affiliation, historical qualifications, other projects you have worked in the past, level & type of computer skills, any other skills, etc.) +
-You and the FreeBSD Project: (free format: other FreeBSD projects you would be interested, anything you'd like to do, comments, etc.) +
-</code> +
- +
-The %%FreeBSD%% Project is a very visible and transparent project, which means that its mailing lists are archived and mirrored in many places on the internet outside of our control. Please use caution when sharing personal information with %%FreeBSD%% on a mailing list, because it is not possible for us to remove any postings from the wider Internet universe after they are sent. +
- +
-===== Login to Weblate ===== +
- +
-Open https://translate-dev.freebsd.org/ and click the 'Login' icon on the right side of the page. +
- +
-{{doc/translation/weblate/0-weblate-login.png?800|login}} +
- +
-You can use your username, email address or your Github account to login. +
- +
-User profile contains your preferences, name and e-mail. Name and e-mail are being used in VCS commits, so keep this information accurate. +
- +
-On our -dev instance, commits will be sent to this [[https://github.com/doc-br/translate/commits/master|repository]], Weblate will commit +
-once a day. +
- +
-===== Find your language team and join in ===== +
- +
-Click Project, choose "%%FreeBSD%% Doc", then click Languages and you will see all the available languages. +
- +
-{{doc/translation/weblate/1-weblate-languages.png?400|languages}} +
- +
-Note that already exists some languages and translated documents in tree[1]. +
- +
-If your language is not using Weblate, you need to get in touch with the language coordinator[2]. +
- +
-1 - https://www.freebsd.org/doc/ +
- +
-2 - https://www.freebsd.org/docproj/translations.html +
- +
-===== Translating online on Weblate ===== +
- +
-This is the easiest way to translate documents, after a coordinator or administrator give you access to the language, the save button will be enabled and you can start translating. +
- +
-{{doc/translation/weblate/2-weblate-documents.png?800|documents}} +
- +
-{{doc/translation/weblate/3-weblate-translate.png?800|translate}} +
- +
-Weblate has a set of links lead to actual translation. The translation is further divided into individual checks, like Untranslated or Needing review. If the whole document is translated, without error, All translations is still available. Alternatively you can use the search field to find a specific string or term. You can see more info about translations in the official Weblate  documentation, like keyboard shortcuts and other tips about the translation tool. +
-[[https://docs.weblate.org/en/latest/user/translating.html#translation-projects]] +
- +
-===== Translating offline ===== +
- +
-If you are familiar with PO Gettext and would like to make offline translation, you can download and upload your translations through the document page on your language, clicking in the Files section. +
- +
-{{doc/translation/weblate/4-weblate-offline.png?800|offline}} +
- +
-===== Translation based on Automatic Suggestions ===== +
- +
-For Languages that were using Weblate before the migration to Hugo/Asciidoctor, they can use this feature from Weblate to save time. +
-There is an open issue to automate this, more details in the Status section. +
- +
-This is a feature from Weblate that uses the Translation Memory generated by the other components and projects on the same server. +
-As we have the old project on the same server, similar strings will match. +
- +
-Strings that match 100/100 in similarity can be copied and saved directly, the other strings will need minor adjusts at least. +
- +
-Some examples: +
- +
-{{doc/translation/weblate/weblate_automatic_suggestion_01.png?800|automatic suggestion 01}} +
- +
-With the migration to Hugo/Asciidoctor the documents are in UTF-8 format, there are places we need to replace HTML entities and in other places we need to adjust the markup, as links. +
- +
-{{doc/translation/weblate/weblate_automatic_suggestion_02.png?800|automatic suggestion 01}} +
- +
-Links: +
- +
-{{doc/translation/weblate/weblate_automatic_suggestion_03.png?800|automatic suggestion 01}} +
- +
-===== Proofreading and Weblate Quality Checks ===== +
- +
-When you click on Project/Language/Document, it will be shown the Translation and String Status from Weblate for that document. This page is very useful for proofreading and quality checks. +
- +
-{{doc/translation/weblate/5-weblate-revision1.png?800|revision1}} +
- +
-In this example,there are eleven strings missing the trailing stop, if you click on that link, it will show only those strings to be revised/translated. +
- +
-{{doc/translation/weblate/6-weblate-revision2.png?800|revision2}} +
- +
-It often appreciated to see the translated strings in their final context in order to do the proofreading more easily. Please refer to the next section to do so. +
- +
-===== Building the Translated Document ===== +
- +
-The translations are built daily and they are available on https://doc.fugbr.org/jenkins/. If you want to speed up this process, you can tell Weblate to commit your translations, then a build process will be triggered immediately through our Jenkins. +
- +
-{{doc/translation/weblate/7-weblate-commit.png?800|commit}} +
- +
-To build it locally, you can follow these steps for documents that are already in the %%FreeBSD%% Doc tree: +
- +
-<code> +
-$ svn checkout https://svn.FreeBSD.org/doc/head doc +
-$ cd doc/pt_BR.ISO8859-1/articles/cups +
-$ cp /tmp/your_po_file.po pt_BR.po +
-$ make tran +
-$ DOCDIR=/tmp/test make all install clean +
-</code> +
- +
-For documents or languages that are not present in the %%FreeBSD%% Doc tree, other steps will be necessary, it can be easy when just adding a new document to an existing language or it can be more complicated when it's a new language. +
- +
-===== Submitting Translations ===== +
- +
-In the book %%FreeBSD%% Documentation Project Primer for New Contributors there is a chapter explaining how submitting translation. +
-[[https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/po-translations-submitting.html]] +
- +
-After committing translations to the offcial doc tree, all translators' names will be added to the list of [[https://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/contrib-additional.html|Additional FreeBSD Contributors]] and other files. +
- +
-if you have any questions, you can always ask on freebsd-translators mailing list.+
  
 ===== Status ===== ===== Status =====
  
-After the migration of the Website and Documentation to Hugo and [[/AsciiDoctor|AsciiDoctor]] was necessary to lock the Weblate project to convert the current workflow to the new format.+After the migration of the Website and Documentation to Hugo and %%AsciiDoctor%% was necessary to lock the Weblate project to convert the current workflow to the new format.
  
 ^ Item ^ Responsible ^ Status ^ Note ^ ^ Item ^ Responsible ^ Status ^ Note ^
-| Weblate project for Documentation | [[/DaniloBaio]] | In Progress | [[https://translate-dev.freebsd.org/projects/documentation/|Documentation Project]] - In progress while we have open issues in the workflow. |+| Weblate project for Documentation | [[/DaniloBaio]] | COMPLETED | [[https://translate-dev.freebsd.org/projects/documentation/|Documentation Project]] |
 | Weblate Project for Website | [[/DaniloBaio]] | In Progress | [[https://translate-dev.freebsd.org/projects/website/|Website Project]] - In progress while we have open issues in the workflow. | | Weblate Project for Website | [[/DaniloBaio]] | In Progress | [[https://translate-dev.freebsd.org/projects/website/|Website Project]] - In progress while we have open issues in the workflow. |
-| Reopen Weblate | [[/DaniloBaio]] | In Progress | More tests with the workflow; Update Wiki; Send maillist announce; |+| Reopen Weblate | [[/DaniloBaio]] | COMPLETED | [[https://lists.freebsd.org/pipermail/freebsd-translators/2021-March/000364.html|Maillist announce]] |
 | Weblate %%FreeBSD%% addon or Admin command | [[/DaniloBaio]] | In Progress | Necessary to adjust components properly. [[https://gist.github.com/dbaio/1de2235e35a2f5bb3363b54dbba4d36e|Weblate FreeBSD notes (gist)]] | | Weblate %%FreeBSD%% addon or Admin command | [[/DaniloBaio]] | In Progress | Necessary to adjust components properly. [[https://gist.github.com/dbaio/1de2235e35a2f5bb3363b54dbba4d36e|Weblate FreeBSD notes (gist)]] |
 | Add more resources to current VM | [[/DaniloBaio]], [[/EdsonBrandi]] | COMPLETED | From 2vCpu/4Gb to 8vCpu/32Gb. Necessary because now there are 500+ Weblate components and it was very slow in the former VM. | | Add more resources to current VM | [[/DaniloBaio]], [[/EdsonBrandi]] | COMPLETED | From 2vCpu/4Gb to 8vCpu/32Gb. Necessary because now there are 500+ Weblate components and it was very slow in the former VM. |
Line 171: Line 19:
 | Translate .toml files |  |  | We can't translate them right now, migrate to .adoc is a way. | | Translate .toml files |  |  | We can't translate them right now, migrate to .adoc is a way. |
 | Language directories |  |  | Hugo don't follow the standard pt_BR, it uses pt-br. Handle it in the scripts. | | Language directories |  |  | Hugo don't follow the standard pt_BR, it uses pt-br. Handle it in the scripts. |
-| New variables in the translations |  |  | Example of variables just in the translated documents, [[https://cgit.freebsd.org/doc/tree/documentation/content/pt-br/articles/bsdl-gpl/_index.adoc#n19|pt-br articles/bsdl-gpl]]. We need that in the original document, otherwise the workflow with po4a won't work properly. | +| New variables in the translations |  |  | Example of variables just in the translated documents, [[https://cgit.freebsd.org/doc/tree/documentation/content/pt-br/articles/explaining-bsd/_index.adoc#n23|pt-br articles/explaining-bsd]]. We need that in the original document, otherwise the workflow with po4a won't work properly. | 
-| Re Enable Jenkins CI for translations |  |  |  | +| Use language variable in includes |  |  | Examples: [[https://cgit.freebsd.org/doc/tree/documentation/content/en/books/porters-handbook/plist/chapter.adoc#n26|books/porters-handbook]], [[https://cgit.freebsd.org/doc/tree/documentation/content/en/books/handbook/book.adoc#n34|books/handbook]]. Maybe there are other places that can use a language variable as well. | 
-| Weblate Automatic Translation |  |  | This is optional, will save time for Languages that were using Weblate before. Basically, we need to write a Django script or addon to find strings with translation suggestion 100/100 and copy that. The addon for Automatic Translation breaks the server on each update, we needed to disable it. |+| po4a: Lines with '+' sign are being translated wrong | [[/DaniloBaio]] | COMPLETED | [[https://cgit.freebsd.org/doc/commit/?id=f80bbbf56d7b9f87e93e25545073b98603da9b81|f80bb]] | 
 +| po4a: Add YAML description string to .po files | [[/DaniloBaio]] | COMPLETED | [[https://cgit.freebsd.org/doc/commit/?id=f2d5f930d82a9f0ccb290dd020173302eceeea02|f2d5f]] | 
 +| Re Enable Jenkins CI for translations | [[/DaniloBaio]] | COMPLETED | [[https://ci.fugbr.org/job/weblate-hugo/|Jenkins]] - [[https://ci.fugbr.org/files/|Jenkins Artifacts (Translations output)]] | 
 +| Weblate Automatic Translation | [[/DaniloBaio]] | In Progress | Testing manual translations for pt_BR; next steps update wiki and send an announcement to the mailing list. [[https://github.com/WeblateOrg/weblate/pull/5764|weblate PR5764]] - [[https://gist.github.com/dbaio/1de2235e35a2f5bb3363b54dbba4d36e|Weblate FreeBSD notes (gist)]] | 
 +| po4a: Fix YAML Front Matter / tags and trademarks | - | - | More details on [[Doc/Translation/Weblate/Documents]] | 
 +| po4a: Do not work properly with tables and callouts | - | - | More details on [[Doc/Translation/Weblate/Documents]] |
  
 ===== FAQ (Frequently Asked Questions) ===== ===== FAQ (Frequently Asked Questions) =====
  • doc/translation/weblate.1615759895.txt.gz
  • Last modified: 2021/03/14 22:11
  • by DaniloBaio