Translating Uyuni to your language - uyuni-project/uyuni Wiki

TL;DR

If you want to go directly to the point, check the "Uyuni is now translatable" slides and video presented at openSUSE + LibreOffice.org Online Conference 2020:

https://github.com/uyuni-project/uyuni/wiki/Presentations#opensuse--libreoffice-online-conference-2020

An Uyuni instance for translators is available and redeployed daily. Send a mail to the translators mailing list for access details.

Introduction

Uyuni is developed in English first and for a long time it has been available only in English. Since Uyuni is a fork of Spacewalk, it inherited partial translations but as they were not maintained, they were disabled.

In mid-2020, SUSE started to reintroduce localization capabilities into Uyuni, per request of SUSE Manager customers.

Scope

A full translation of Uyuni comprises several "blocks":

  • WebUI
  • Command-line tools
  • Documentation
  • YaST module

Each of those blocks, in turn, comprises several pieces.

Help

The best place for translators to ask questions is the uyuni-translation mailing list. Please note as of this writing, this mailing list only supports plain text e-mail (this will be solved soo).

Next to that, Gitter, Uyuni Community Hours or any of the other official contact methods are good.

Plan for translation

It is important to note translating Uyuni is not an "all or nothing" effort: you may translate progressively.

First of all, you should identify who your target user is:

  • Does he use mostly the command-line tools?
  • The WebUI?
  • Or maybe he would feel comfortable with using the WebUI and command-line tools in English, and he only wants the documentation to be translation?

Now that you know where to start, one piece of advice: prefer to translate full "blocks", i. e. do not translate a few pages of the WebUI, then some half the installation guide, then 30% of the core command-line tools "block". That kind of translation cannot be made available by default (and maybe not even shipped) because it's everything is incomplete. On the other hand, if you only translate the Installation Guide, that's a perfectly shippable translation.

How to translate

The source code of Uyuni is all hosted in git repositories, check this page for details:

https://www.uyuni-project.org/pages/source-code.html

To make things easy for translators, we are using the openSUSE WebLate instance to translate Uyuni:

https://l10n.opensuse.org/projects/uyuni/

Strings are pulled from git to WebLate, and pushed the other way around, every few hours in an automated process.

To avoid breaking WebLate because of merge conflicts, translating directly in the git repositories (i. e. a pull request to a GitHub repository which modifies target-language translation files) is NOT allowed. The only exception is translating screenshots, details in the documentation section below.

Translation components

What I called "blocks" earlier is called "components" in WebLate terminology. Let's dig deeper into them.

WebUI

As a consequence of the evolution of the Uyuni WebUI and the different technologies used, the strings in the WebUI are split into several WebLate components:

Java

The Java component in WebLate contains the translations for the keys used in java classes, mainly struts actions and related helpers. These keys then will be reflected on the UI pages based on the result of the current action.

Source

XLIFF files are used in Uyuni java codebase. Classes where most of these keys will be used are here

https://github.com/uyuni-project/uyuni/tree/master/java/code/src/com/redhat/rhn/manager

and the XLIFF source file contains a reference to where each string comes from:

https://github.com/uyuni-project/uyuni/blob/master/java/code/src/com/redhat/rhn/frontend/strings/java/StringResource_en_US.xml

JSP

The Java-JSP component in WebLate contains the translations for the keys used in JSPs. These keys then will be reflected on the UI pages based on the result of the current action.

Source

JSPs, where these keys are being used:

https://github.com/uyuni-project/uyuni/tree/master/java/code/webapp/WEB-INF/pages

and the XLIFF source file contains a reference to where each string comes from is

https://github.com/uyuni-project/uyuni/tree/master/java/code/src/com/redhat/rhn/frontend/strings/jsp/StringResource_en_US.xml

Nav

The Java Nav component in WebLate contains the translations for the keys used in java classes that build the Navigation menus.

Source

Classes where these keys are being used:

https://github.com/uyuni-project/uyuni/tree/master/java/code/src/com/redhat/rhn/frontend/events

and the XLIFF source file contains a reference to where each string comes from is

https://github.com/uyuni-project/uyuni/tree/master/java/code/src/com/redhat/rhn/frontend/strings/nav/StringResource_en_US.xml

Template

The Java Template component in WebLate contains the translations for the keys used in java classes that are used for backend events and actions.

Source

Classes where these keys are being used:

https://github.com/uyuni-project/uyuni/tree/master/java/code/src/com/redhat/rhn/frontend/events

and the XLIFF source file contains a reference to where each string comes from is

https://github.com/uyuni-project/uyuni/blob/master/java/code/src/com/redhat/rhn/frontend/strings/template/StringResource_en_US.xml

Command-line tools

Backend

The backend component in WebLate contains the translations for the backend tools required by any Uyuni Server: spacewalk-repo-sync, mgr-inter-sync, Oracle ULN authenticator, diskchecker, taskomatic, etc.

Source

Those tools implement i18n using gettext. The source code is here:

https://github.com/uyuni-project/uyuni/blob/master/backend/

and the gettext catalog file contains a reference to where each string comes from:

https://github.com/uyuni-project/uyuni/blob/master/backend/po/spacewalk-backend-server.pot

Uyuni Server daemon

The mgr-daemon component contains the translations for the Server-side of of the traditional client tools.

Source

The source code is here:

https://github.com/uyuni-project/uyuni/tree/master/client/rhel/mgr-daemon

and the gettext catalog file contains a reference to where each string comes from:

https://github.com/uyuni-project/uyuni/blob/master/client/rhel/mgr-daemon/po/rhnsd.pot

Traditional stack client tools

The spacewalk-client-tools component contains the translation for the client-side of the of the traditional client tools.

Source

The source code is here:

https://github.com/uyuni-project/uyuni/tree/master/client/rhel/spacewalk-client-tools

and the gettext catalog file contains a reference to where each string comes from:

https://github.com/uyuni-project/uyuni/blob/master/client/rhel/spacewalk-client-tools/po/rhn-client-tools.pot

Yum plugin for RHN

The yum-rhn-plugin component contains the translations of another piece of the traditional client tools, specific to yum-based distributions (RHEL, CentOS, Oracle Linux 6 and 7), to connect to the RH CDN.

Source

The source code is here:

https://github.com/uyuni-project/uyuni/tree/master/client/rhel/yum-rhn-plugin

and the gettext catalog file contains a reference to where each string comes from:

https://github.com/uyuni-project/uyuni/blob/master/client/rhel/yum-rhn-plugin/po/yum-rhn-plugin.pot

ABRT plugin

The spacewalk-abrt component contains the translatios of the ABRT crash reporter.

Advice: do not translate this unless you are really bored, it will probably be removed soon.

The source code is here:

https://github.com/uyuni-project/uyuni/tree/master/client/tools/spacewalk-abrt

and the gettext catalog file contains a reference to where each string comes from:

https://github.com/uyuni-project/uyuni/blob/master/client/tools/spacewalk-abrt/po/spacewalk-abrt.pot

YaST module

The susemanager component contains the translatios for the YaST module to configure Uyuni after installation.

Source

If you want to check where some string is used, you can find the code where these strings where extracted in the Ruby (.rb) files here:

https://github.com/uyuni-project/uyuni/tree/master/susemanager/yast

and the gettext catalog file contains a reference to where each string comes from:

https://github.com/uyuni-project/uyuni/blob/master/susemanager/po/susemanager.pot

Look for strings enclosed in the usual "_" (underscore) gettext prefix, e. g. susemanager/yast/susemanager_db.rb

Popup.Error(
Builtins.sformat(
_("The password should have at least %1 characters."),
7
)
)

Documentation

You can read the documentation in English in the Uyuni website: https://www.uyuni-project.org/uyuni-docs/uyuni/index.html

Keywords

The documentation uses a few keywords: btn, menu, etc. Be careful you do not translate that when translating the string, or you will break the output format (HTML and/or PDF).

For example, this text in English:

From the menu:Uyuni Setup[Database Settings] screen, enter a database user and password and click btn:[Next] to continue.

would be translated to Spanish as

Desde la pantalla menu:Configuración de Uyuni[Configuración de base de datos], introduzca un usuario y contraseña de base de datos y clique btn:[Siguiente] para continuar.

For cross-references (i. e. links to other pages), you should translate what's inside square brackets. E. g this text in English

xref:qs-publiccloud-overview.adoc[Quick Start: Public Cloud]

would be translated to Czech as

xref:qs-publiccloud-overview.adoc[Rychlý start: Veřejný cloud]

Be careful not to break markup: if you split btn, xref, etc then the outcome will be markup text (i. e. you will see "btn: [Siguiente]"), not the marked-up text (i. e. a button with the text "Siguiente").

Source

The Uyuni documentation is written in AsciiDoc format (source files here).

Since neither WebLate nor any other translation tool supports AsciiDoc natively, we convert it to gettext (.pot/.po), submit it to WebLate and then do the opposite. Translated AsciiDoc is generated at build time, it is not stored in the git repository.

Toolchain

The uyuni-docs wiki contains explains in full detail how to set up the Antora + AsciiDoctor toolchain to build HTML and PDF documentation from sources. https://github.com/uyuni-project/uyuni-docs/wiki

A virtual machine with all the tooling, a clone of the git repository in your home directory (make sure you git pull before you do anything!) and a browser (in case you want to translate in WebLate directly from the VM) is available here: https://github.com/uyuni-project/uyuni-docs-toolchain-vm/releases

In order to build all the enabled translations, just run

$ make antora-uyuni

If you want to build a single language, run the target with the langcode, e. g. for Spanish:

$ make antora-uyuni-es

To enable a new language:

  1. Create a new translation for those components in WebLate. This is truly the easiest way to start.
  2. Duplicate the Makefile.es file with the appropriate suffix for your language (e. g. Makefile.jp)
  3. Include it at the end of the Makefile file
  4. Add it to the antora-suma and antora-uyuni targets
  5. Replace and re-suffix as needed the LANGCODE_ES, LANGDIR_ES, HTML_BUILD_DIR_ES, etc at the top of your new Makefile.jp: the would now be LANGCODE_JP, LANGDIR_JP, HTML_BUILD_DIR_JP, etc.

Screenshots

It is important to note all guides contain some screenshots.

At this moment, WebLate cannot manage "translation" of screenshots (i. e. taking a screenshot of the screen in the target language and replacing the screenshot in English), so the only way to provide "translated" screenshots is to create a pull request to the uyuni-docs git repository in GitHub.

This is the only case where translations are allowed outside WebLate.

Limitations

As of this writing, the following parts of Uyuni are not enabled for translation:

  • dnf-plugin-spacewalk
  • None of the tools in the utils directory, even though we ship them in the spacewalk-utils and spacewalk-utils-extra packages

Enabling them for translation is rather easy (a matter of adding wrapping the strings for gettext, adding a few lines of boilerplate code and a Makefile target to extract them). Contributions are welcome!