Translate FreeBSD on Weblate

Introduction

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/books/fdp-primer/.

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 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 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.

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.)

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.

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 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.

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.

documents

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.

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:

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.

automatic suggestion 01

Links:

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.

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.

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://ci.fugbr.org/files/, you can follow the build jobs here. 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.

commit

To build it locally, you can follow these steps for documents that are already in the FreeBSD Doc tree:

$ git clone https://github.com/doc-br/freebsd-doc-weblate && cd freebsd-doc-weblate

  # for pt_BR Language
$ KEEP_ENV=0 ./tools/translate.sh documentation pt_BR

  # or, translate only .PO files with more than 80% of translations
$ ./tools/translate.sh documentation pt_BR


  # Necessary step only for Weblate languages that don't use the 
  # same directory name in the project.
  # 'pt_BR' needs; 'es' don't;
$ cp -aRfv documentation/content/pt_BR/* documentation/content/pt-br/


  # This will build the 'documentation' and 'website'
$ make

  # This will build only the 'documentation'
$ make documentation

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/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 Additional FreeBSD Contributors and other files.

if you have any questions, you can always ask on freebsd-translators mailing list.

Status

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

Weblate project for Documentation

DaniloBaio

COMPLETED

Documentation Project

Weblate Project for Website

DaniloBaio

In Progress

Website Project - In progress while we have open issues in the workflow.

Reopen Weblate

DaniloBaio

COMPLETED

Maillist announce

Weblate FreeBSD addon or Admin command

DaniloBaio

In Progress

Necessary to adjust components properly. 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.

po4a: Hugo/AsciiDoctor support (Major)

DaniloBaio

COMPLETED

po4a maillist - po4a v0.63

po4a: Asciidoc attributes issue (Major)

DaniloBaio

COMPLETED

po4a PR298 - po4a v0.63_1

Ignore chapters-order.adoc files

DaniloBaio

COMPLETED

update_translate_template.sh

Ignore toc*.adoc files

DaniloBaio

COMPLETED

update_translate_template.sh#L32

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.

New variables in the translations

Example of variables just in the translated documents, pt-br articles/explaining-bsd. We need that in the original document, otherwise the workflow with po4a won't work properly.

Use language variable in includes

Examples: books/porters-handbook, books/handbook. Maybe there are other places that can use a language variable as well.

po4a: Lines with '+' sign are being translated wrong

DaniloBaio

COMPLETED

f80bb

po4a: Add YAML description string to .po files

DaniloBaio

COMPLETED

f2d5f

Re Enable Jenkins CI for translations

DaniloBaio

COMPLETED

Jenkins - 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. weblate PR5764 - 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)

* Do we need to translate Copyright messages?

Every language team decides this for their own language, in pt_BR (Brazilian Portuguese) team, we decided not to translate those messages.

Credits

Document based on Fedora article about Zanata. https://fedoraproject.org/wiki/L10N/Translate_on_Zanata


CategoryServices

Doc/Translation/Weblate (last edited 2021-08-14T12:56:44+0000 by DaniloBaio)