Translate FreeBSD on Weblate

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

Weblate is an open source software web-based focused on localization, we run our own local instance.

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.

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.

Open https://translate-dev.freebsd.org/ and click the 'Login' icon on the right side of the page.

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.

Click Project, choose “FreeBSD Doc”, then click Languages and you will see all the available 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

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.

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

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.

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:

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.

Links:

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.

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.

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.

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.

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

$ 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

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.

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

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

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.

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

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