Chapter 10. Weblate Translations

10.1. Introduction

This chapter describes some basic steps for joining the FreeBSD translators team, translating online on Weblate or offline, and some simple suggestions on translating, proofreading, and testing. It’s focused on the translation part.

The original documents (articles and books) are in the documentation portal.

Weblate is web-based open-source software focused on localization; the FreeBSD project runs a local instance.

10.2. How to Become a FreeBSD Translator

Following are simple steps to start translating articles and books of the FreeBSD Documentation Project.

Create an account on the FreeBSD Weblate instance with an email address or your GitHub account.
Subscribe to the FreeBSD translators mailing list.
Introduce yourself and ask to join a language team. If the language team does not exist, ask to create it. The self-introduction is essential. It raises your chances of being approved for write access.
Login to Weblate with the new account.
Find the language team and choose an initial document to translate.
Create a Bugzilla account to submit the translations after finishing a document. The Documentation project is also accepting GitHub Pull Requests with translation submissions.

All translation files and documents must follow The FreeBSD Documentation License; if this is unacceptable, please do not sign up or send any patches or translations.

10.3. Introduce Yourself

Please provide a brief self-introduction on the FreeBSD translators mailing list to initiate the process of granting access. This will enable a language coordinator or administrator to provide the necessary permissions for the new user of Weblate to start translating.

Following is an example of how such an email could look.

Subject: Self-Introduction: Name and language

Name:      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 -- info which you feel comfortable sharing with
  others: company, school, other affiliation, historical qualifications, other
  projects you have worked on, level and type of computer skills, other relevant skills,
  etc.)
You and the FreeBSD Project: (free format: other FreeBSD projects of
  interest, comments, etc.)

Open https://translate-dev.freebsd.org/ and Sign in.

Use a username, email address, or GitHub account to log in.

The user profile contains your preferences, name, and email address. The name and address will be used in commits; keep this information accurate.

On the FreeBSD Weblate instance, all translations will be committed to freebsd-doc-translate (an intermediate repository on GitHub), not directly to freebsd-doc. Translators must take the PO gettext files (.po), converting them to .adoc and submit it via Bugzilla or GitHub to get the translated document published or updated in the documentation portal. See more in the following sections.

Weblate will commit daily, at least to freebsd-doc-translate, if any new strings are translated.

10.5. Find a Language Team to Join In

Click Projects, choose Documentation, then click Languages, and see all the available languages.

Note that some languages and translated documents already exist in the documentation portal and repositories.

If the desired language for translation is not available in Weblate, please contact the language coordinators before asking to create a new language. If there is no answer, then write to the Documentation Engineering Team <doceng@FreeBSD.org>.

10.6. Translating Online on Weblate

Translating documents online proves to be the easiest method for document translation on FreeBSD, as it allows users to collaborate on the same file, distributing the workload.

Once a coordinator or administrator grants access to a specific language for a username, the save button will be enabled, so that this user can start translating.

Weblate has a set of links that lead to actual translation. The translation is further divided into individual checks, like Untranslated or Needing review. If the whole document is translated without any error, All translations link is still available in case a review is necessary. Alternatively, the search field can be used to find a specific string or term.

In the Weblate documentation, there is more info about translations, like keyboard shortcuts and other tips about the translation tool.

10.7. Translating Offline

Weblate on FreeBSD uses PO gettext files for translations. Users familiar with PO gettext files that want to translate offline can download and upload the translations through the document page on Weblate by clicking in the Files section.

10.8. Translation based on Automatic Suggestions

Languages using Weblate before the migration to Hugo/Asciidoctor can use this feature from Weblate to save time.

This feature from Weblate uses the Translation Memory generated by the other components and projects on the same server. The former Weblate translations are hosted on the same server as read-only for that.

Strings that match 100/100 in similarity can be copied and saved directly. Other strings will need at least minor adjustment.

Some examples:

With the migration to Hugo/Asciidoctor, documents use UTF-8. Some HTML entities should be replaced. Some strings, such as links, require changes to markup.

Links:

10.9. Proofreading and Weblate Quality Checks

The document dashboard Project/Language/Document shows the translation status and string status for that document. This page is handy for proofreading and quality checks.

In this example, two strings are missing the full stop; following that link will show only those strings to be revised/translated.

Translators and reviewers often value observing translated strings in context.

10.10. Building the Translated Document

The project does not use continuous integration and continuous delivery to build translations. There are studies to make it available.

The following example uses GitHub, as Weblate is also on GitHub. Note that this repository is a read-only mirror, but Pull Requests are accepted.

To build the translation locally, follow these steps:

Procedure: Clone the necessary repositories

Clone the freebsd-doc repository:

% git clone https://github.com/freebsd/freebsd-doc.git ~/freebsd-doc

Clone the freebsd-doc-translate repository:

% git clone https://github.com/freebsd/freebsd-doc-translate.git ~/freebsd-doc-translate

Procedure: Copy a translation file to freebsd-doc

With both repositories in place, copy the translation from freebsd-doc-translate to freebsd-doc. Example of the Committer’s Guide article translation in Spanish.

% cp ~/freebsd-doc-translate/documentation/content/es/articles/committers-guide/_index.po \
~/freebsd-doc/documentation/content/es/articles/committers-guide/

Procedure: Convert a translation file (.po) to .adoc

Go to the root of freebsd-doc.

% cd ~/freebsd-doc

Translate (convert) the .po file to .adoc

% ./tools/translate.sh documentation es articles/committers-guide

By default: only files with more than eighty percent of strings translated will be converted to .adoc.

To ignore that limit:

% KEEP_ENV=0 ./tools/translate.sh documentation es articles/committers-guide

Some documents, like books, have many PO gettext files. Always copy all of them when translating and building. Files that weren’t translated will be converted with the source (English) strings.

The directory structure is fundamental. Always follow the English document directory structure.

Procedure: Build the translated document

Last, the building part.

Enter the documentation directory because there is no need to build the FreeBSD website.

% cd documentation

And build the documentation. Note that en is always added by default when building any other language.

% DOC_LANG=es make

This command will build only the English and Spanish documents of the FreeBSD documentation portal. The output will be in the public directory; open that in a browser. Note that some index files can redirect the browser to the online page.

Another good option is to build and serve the content with Hugo’s internal webserver:

% DOC_LANG=es make run

By default, the webserver listens on localhost; To override this behavior, specify the desired IP address in the BIND parameter value.

% DOC_LANG=es make run BIND=192.168.15.10

This builds and serves the content with Hugo’s internal webserver and lets it open, and if any file changes, it rebuilds them automatically.

To make any necessary adjustments in the translation, follow the steps below to re-sync all components:

Fix the translation string on Weblate.
Force Weblate to commit the changes on Document/Manage/Commit section.
Sync the local Weblate repository freebsd-doc-translate with a git pull origin main command.
Copy the translation again to freebsd-doc.
Convert the translation to .adoc with the ./tools/translate.sh script.
Hugo will rebuild the file and not build the entire set if make run was used; or re-execute make.

Follow the previous steps as many times as is necessary until the document is ready to be published.

The Documentation Build Process chapter includes information about rendering to HTML and PDF.

10.11. Submitting Translations

Example of submitting an update to the Brazilian Portuguese article Committer’s Guide.

Check the repository

After following the steps in Building the Translated Document, go to the root of freebsd-doc and preview what’s to be committed. For an overview of files to be changed, and differences in file content:

% git status
% git diff

Review the output, and if any files unrelated to the Committer’s Guide translation update were changed or added, take the appropriate action of reverting or removing them, respectively, before proceeding further.

Always include the PO gettext file (.po) and the translated document in Hugo/Asciidoctor (.adoc).

Create a new branch and commit

Create another branch to separate the work, which will help with future updates in the local repository.

% git checkout -b committers-guide_pt-br

% git add .
% git commit

Example of commit messages for translations:

pt-br/committers-guide: Sync with en XXXXXXX

Where XXXXXXX is the git(1) revision stored in the Weblate repository ~/freebsd-doc-translate/revision.txt.

If it is the first translation of an article:

Add Korean translation of Leap Seconds article

A message will be displayed after the commit if git(1) has not been configured previously. Please follow the instructions and provide the name and email address used on Weblate. This step is crucial to proper crediting of contributors.

Then check the entire commit, review changes, and author name and email.

% git show

Generate a patch

Next, generate a git-format-patch(1) file.

% git format-patch main
0001-pt-br-committers-guide-Sync-with-en-XXXXXXX.patch

Attach the patch 0001-pt-br-committers-guide-Sync-with-en-XXXXXXX.patch to a problem report in FreeBSD Bugzilla.

Include the following information in the report:

Table 1. Bugzilla Fields
Field	Value
product	Documentation
Component	Books & Articles
Summary	Same as the local commit
Description	State that instructions in this guide were followed, including proofreading and other necessary steps. Include things that may help with triage and progression of the report.
CC (Optional)	If the language has coordinators, include their email addresses in the CC field.

For people familiar with git(1) and GitHub: instead of submitting the patch through Bugzilla, a GitHub pull request can be used (use the name and address that you use with Weblate).

https://github.com/freebsd/freebsd-doc/ is a secondary mirror. Changes to the doc tree can be made only by people who have a doc commit bit.

When translators keep sending good-quality patches, they can be nominated by other committers to receive write-access (a doc commit bit for translations), a FreeBSD account, and associated perks.

The list of Additional FreeBSD Contributors includes non-committers whose contributions are committed to the doc tree.

If in doubt about any procedure, write to the FreeBSD translators mailing list.

10.12. FAQ (Frequently Asked Questions)

10.12.1. Is it necessary to translate all the Copyright messages?

Every language team decides this for their language; in pt-br (Brazilian Portuguese) team, it was decided not to translate those messages.

Last modified on: March 9, 2024 by Danilo G. Baio

Home