-
Notifications
You must be signed in to change notification settings - Fork 186
Translating Uyuni to your language
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:
An Uyuni instance for translators is available and redeployed daily. Send a mail to the translators mailing list for access details.
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.
A full translation of Uyuni comprises several "blocks":
- WebUI
- Command-line tools
- Documentation
- YaST module
Each of those blocks, in turn, comprises several pieces.
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.
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.
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.
What I called "blocks" earlier is called "components" in WebLate terminology. Let's dig deeper into them.
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:
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.
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:
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.
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
The Java Nav component in WebLate contains the translations for the keys used in java classes that build the Navigation menus.
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
The Java Template component in WebLate contains the translations for the keys used in java classes that are used for backend events and actions.
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
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.
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
The mgr-daemon component contains the translations for the Server-side of of the traditional client tools.
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
The spacewalk-client-tools component contains the translation for the client-side of the of the traditional client tools.
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:
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.
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
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
The susemanager component contains the translatios for the YaST module to configure Uyuni after installation.
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
)
)
- docs ROOT: common elements to all documentation guides
- docs installation: Installation Guide. You should start here.
- docs upgrade: Upgrade Guide. Another must-have.
- docs client-configuration: Client Configuration Guide. Another must-have.
- docs retail: Uyuni for Retail specific bits
- docs salt: Salt Guide.
- docs administration: Administration Guide. Huge.
- docs reference: Reference Guide. Huge.
- docs quickstart-public-cloud: QuickStart Guide for Public Cloud. Short and provides useful information. You should translate it after the Client Configuration Guide.
- docs quickstart-sap: QuickStart Guide for SAP users. Short and provides useful information.
- docs large-deployments: Large Deployments Guide
- docs architecture: Architecture Guide. Do not translate, as it is still incomplete in English.
You can read the documentation in English in the Uyuni website: https://www.uyuni-project.org/uyuni-docs/uyuni/index.html
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").
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.
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:
- Create a new translation for those components in WebLate. This is truly the easiest way to start.
- Duplicate the
Makefile.esfile with the appropriate suffix for your language (e. g.Makefile.jp) - Include it at the end of the
Makefilefile - Add it to the
antora-sumaandantora-uyunitargets - 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.
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.
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-utilsandspacewalk-utils-extrapackages
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!